DEV Community: Russell Jones

Day One of the Content Pipeline: What Broke and What I Fixed

Russell Jones — Mon, 06 Apr 2026 04:01:00 +0000

Ahnii!

Yesterday's post walked through automating a content pipeline with GitHub Actions and Issues. The idea: a daily scheduled job scans recent commits and closed issues across several repos, filters out the noise, and opens what's left as GitHub issues labeled stage:mined. One of those issues looks something like this:

Title: [content] feat: add SovereigntyProfile to Layer 0
Body:
  ## Source
  Commit `abc1234` in `waaseyaa/framework`
  ## Content Seed
  feat: add SovereigntyProfile to Layer 0
  ## Suggested Type
  text-post

Those issues are raw material. You curate them into drafts, produce the copy, and publish. That surfacing step is what the rest of this post calls mining. This post is about what happened the first time I actually ran that pipeline. The short version: it works, but the first real run turned up three problems no amount of planning could have caught. Here are the three fixes and the meta-lesson underneath them.

Day One Output: 20 Issues, Too Much Noise

The mining workflow fired on schedule and opened 20 stage:mined issues overnight, pulled from three repos. Good news: the pipeline saw everything it was supposed to see. Bad news: "everything" is not the same as "a usable drafting queue." The first run had more noise than I expected, and it had noise the filter couldn't see.

Fix 1: Tighten the Mining Filter

Even with the v1 noise filter, too many low-signal commits made it through. Things like fix: align FileRepositoryInterface usage with Waaseyaa\Media\File contract matter for the codebase and are boring as standalone posts. The first fix was to extend the exclude regex in content-mine.yml:

COMMITS=$(gh api "repos/$REPO/commits?since=$SINCE&per_page=50" \
  --jq '.[] | select(.commit.message | test("^(Merge |chore|docs|fix typo|bump|update dep|Bump |fix:.*([Pp]hp[Ss]tan|namespace|alignment|placeholder|phpunit|mock|ignore|typo))"; "i") | not) | {sha: .sha[0:7], message: (.commit.message | split("\n") | .[0]), date: .commit.author.date}' \
  2>/dev/null || echo "")

The new patterns (phpstan, namespace, alignment, placeholder, phpunit, mock, ignore, typo) catch categories of real work nobody wants to read about. A minimum message length of 25 characters cuts drive-by fixes. Fewer mined issues per run, and the ones that survive sit closer to "actually postable." That handled the mechanical noise. The next problem was harder because no regex could see it.

Fix 2: Merge-in-Curation

Filters are a blunt instrument. They cannot tell that eight separate commits all belong to the same post. On day one, the Giiken project alone produced eight mined issues: scaffold, entity types, RBAC, ingestion, wiki schema, query layer, plus two support commits. Every one of them was a valid feature commit. Together they were one post. No filter was going to catch that. Only a human reading them side by side could say "these are a story."

So curation got a new action: merge into target. Instead of picking one winner and closing the rest, you pick a canonical issue, roll the seeds from the others into its body, and close the sources. The target ends up carrying a combined seed (the whole story), and the sub-issues get a skipped label and a closed state.

The curation skill now runs like this:

→ Approve (move to stage:curated)
→ Skip   (close with skipped label)
→ Merge  (pick target, combine seeds, close sources)
→ Edit   (adjust seed, type, or channels before approving)

Running that over the 20 mined issues collapsed them to 4 curated posts: one about the pipeline itself, one about the Giiken project, one about a governance protocol suite in the framework, and one about a specific Symfony refactor. Signal up, count down. Two fixes done. The third was the embarrassing one.

Fix 3: Put the Blog First

The v1 production step went straight from a curated issue to Facebook, X, and LinkedIn copy. That read fine in the design doc. It fell apart the first time I tried to run it, because every one of those social posts had a placeholder where the URL should go. The URL had to point at a blog post. The blog post did not exist yet.

So I rewrote the /content-produce skill — a Claude Code workflow that turns queue issues into drafts. The new flow:

flowchart TD
    A[stage:curated issue] --> B[Draft Hugo post<br/>draft: true]
    B --> C[Draft social copy<br/>docs/social/slug.md]
    C --> D[Commit both to blog repo]
    D --> E{Human review}
    E -->|Flip draft: false| F[GitHub Actions deploys]
    F --> G[/content-pipeline/]
    G --> H[Buffer API → X, LinkedIn, Facebook]

The human controls publication. The skill commits drafts only and never flips draft: false. Once I flip the flag and push, GitHub Actions deploys the post, and a separate /content-pipeline skill handles the Buffer API for social distribution. Each step has one job. This post you're reading is the first one produced by the new flow.

Why Content Pipelines Need Continuous Refinement

You cannot design a content pipeline in the abstract. You ship v1, run it against one day of real input, and watch it lie to you. Then you fix the specific lies. That loop is the work.

Three days ago this pipeline did not exist. Two days ago it was a spec. Yesterday it shipped. Today it is already different. None of the three fixes in this post were things I could have known up front. They came from running the thing, staring at the output, and asking "what is this queue actually trying to tell me?"

If you are building your own version of this, expect the same arc. Your v1 will have noise you cannot see yet. Your first curation session will reveal merges a filter could not find. And your production step will probably be backwards, because writing the fun part first (the tweets) is more tempting than writing the part that does the work (the blog post). The refinement is not a sign something went wrong. It is the point.

Baamaapii

Domain routing in Waaseyaa: replacing a giant dispatcher with small routers

Russell Jones — Mon, 06 Apr 2026 01:36:27 +0000

Ahnii!

Waaseyaa had a controller dispatcher that grew past 1,000 lines. Every new feature meant more conditionals in the same file. This post covers how that dispatcher was replaced with domain-specific routers, each implementing a two-method interface that keeps routing logic scoped and testable.

What a Dispatcher Does

graph TD
    A[HTTP Request] --> B[Router]
    B -->|matches URL to route| C[Dispatcher]
    C -->|picks controller, injects context| D[Controller]
    D --> E[Response]

The router matches a URL to a route definition. The dispatcher takes that match and figures out which controller to instantiate, which method to call, and how to pass in the request context. In most frameworks, you never think about it because the framework handles it for you.

The problem starts when the dispatcher becomes the place where "which code to run" turns into a long chain of conditionals.

Why a Monolithic Dispatcher Breaks Down

A single dispatcher that handles every request type accumulates conditionals fast. You end up with something like this:

public function dispatch(Request $request): Response
{
    $controller = $request->attributes->get('_controller');

    if ($controller === 'entity_types') {
        // 40 lines of entity type listing logic
    } elseif (str_starts_with($controller, 'entity_type.')) {
        // 60 lines of lifecycle management
    } elseif ($controller === 'openapi') {
        // 80 lines of OpenAPI spec generation
    } elseif (str_contains($controller, 'SchemaController')) {
        // 50 lines of schema handling
    }
    // ... and so on for every domain
}

Entity CRUD, schema generation, lifecycle management, OpenAPI docs: all funneling through one class. Each new feature adds another branch, and testing any one path means loading the context for all of them.

The fix isn't a better dispatcher. It's smaller, focused routers that each own one domain.

The DomainRouterInterface Contract

A domain router is a small class that owns one slice of your application's request handling. Instead of one dispatcher knowing about every domain, each router answers two questions: "Is this request mine?" and "How do I handle it?" The interface makes this explicit:

interface DomainRouterInterface
{
    // "Is this request mine?" — inspects the request, returns a boolean.
    public function supports(Request $request): bool;

    // "Yes, handle it." — does the work, returns a response.
    public function handle(Request $request): Response;
}

// The dispatcher iterates registered routers in order.
// First one to return true from supports() wins.

This is the Chain of Responsibility pattern with an explicit contract.

EntityTypeLifecycleRouter: A Complete Example

Waaseyaa lets you define entity types (think "Article", "User", "Comment"). Sometimes you need to disable one, maybe you're deprecating a content type, or re-enable one that was turned off. That's what this router handles. Here's the full class:

final class EntityTypeLifecycleRouter implements DomainRouterInterface
{
    use JsonApiResponseTrait; // consistent JSON:API response formatting

    public function __construct(
        // Registry: knows which entity types exist and their capabilities
        private readonly EntityTypeManager $entityTypeManager,
        // Handles disable/enable state changes
        private readonly EntityTypeLifecycleManager $lifecycleManager,
    ) {}

    public function supports(Request $request): bool
    {
        // Prefix match: anything starting with "entity_type." belongs here.
        // Adding entity_type.archive later requires zero changes to this method.
        $controller = $request->attributes->get('_controller', '');

        return $controller === 'entity_types'
            || str_starts_with($controller, 'entity_type.');
    }

    public function handle(Request $request): Response
    {
        $controller = $request->attributes->get('_controller', '');

        return match ($controller) {
            'entity_types'        => $this->listTypes($request),
            'entity_type.disable' => $this->disableType($request),
            'entity_type.enable'  => $this->enableType($request),
            default               => $this->jsonApiResponse(404, []),
        };
    }
}

One class, one domain, fully testable in isolation.

SchemaRouter: Same Pattern, Different Domain

Your API also needs to serve OpenAPI specs and schema definitions for each entity type. That's a different domain from lifecycle management, so it gets its own router:

final class SchemaRouter implements DomainRouterInterface
{
    use JsonApiResponseTrait;

    public function __construct(
        private readonly EntityTypeManager $entityTypeManager,
        // Schema endpoints enforce the same access rules as the entities themselves.
        // Can't access an entity type? Can't read its schema either.
        private readonly EntityAccessHandler $accessHandler,
    ) {}

    public function supports(Request $request): bool
    {
        $controller = $request->attributes->get('_controller', '');

        return $controller === 'openapi'
            || str_contains($controller, 'SchemaController');
    }

    public function handle(Request $request): Response
    {
        $controller = $request->attributes->get('_controller', '');

        if ($controller === 'openapi') {
            return $this->generateOpenApiSpec($request);
        }

        // SchemaController routes carry the entity type as a route parameter
        $entityType = $request->attributes->get('entity_type_id', '');
        return $this->showSchema($entityType, $request);
    }
}

Both routers pull typed context from the request without doing any parsing themselves. Where does that context come from?

Routers Get a Fully Loaded Request

Middleware upstream handles authentication, body parsing, and context assembly before any router sees the request:

// By the time handle() runs, the request carries everything the router needs.
// No token parsing, no JSON decoding, no service lookups.
$account = $request->attributes->get('_account');           // authenticated user
$storage = $request->attributes->get('_broadcast_storage'); // storage backend
$body    = $request->attributes->get('_parsed_body');       // deserialized JSON
$context = $request->attributes->get('_waaseyaa_context');  // framework context

The infrastructure work happens once, upstream. Routers stay focused on domain logic.

Adding a New Router

Here's a skeleton for a new domain. Say you want to handle bulk import operations:

final class BulkImportRouter implements DomainRouterInterface
{
    use JsonApiResponseTrait;

    public function supports(Request $request): bool
    {
        return str_starts_with(
            $request->attributes->get('_controller', ''),
            'bulk_import.',
        );
    }

    public function handle(Request $request): Response
    {
        $controller = $request->attributes->get('_controller', '');

        return match ($controller) {
            'bulk_import.csv'  => $this->importCsv($request),
            'bulk_import.json' => $this->importJson($request),
            default            => $this->jsonApiResponse(404, []),
        };
    }
}

No existing router changes. No dispatcher modifications. Register it in the router collection and the dispatcher picks it up. The interface guarantees new domains are additive.

What This Gets You

The 1,000-line dispatcher is gone. In its place: small classes with clear boundaries, each testable in isolation:

$router = new EntityTypeLifecycleRouter($entityTypeManager, $lifecycleManager);
$request = new Request();
$request->attributes->set('_controller', 'entity_type.disable');
$request->attributes->set('_parsed_body', ['entity_type_id' => 'article']);

$response = $router->handle($request);
// No framework boot, no database, no middleware chain

When you see a request to entity_type.disable, you know exactly which file handles it. No tracing through a switch statement in a god class.

Baamaapii

Remember when server-side rendering was just rendering?

Russell Jones — Mon, 06 Apr 2026 00:41:04 +0000

Ahnii!

Somewhere around 2016, "server-side rendering" stopped meaning "the server renders HTML." It started meaning "run your JavaScript framework on the server so it can produce the HTML that the browser will then throw away and rebuild." The industry just forgot what to call it after React came along.

Waaseyaa's SSR package does the original thing. A request comes in. PHP resolves a template. Twig renders HTML. The server sends it back. No hydration step, no virtual DOM diffing, no 200MB node_modules folder for the privilege of generating a <div>.

This post walks through how the rendering pipeline works: from request to HTML, with the entity renderer, field formatters, and theme chain loader that make it more than echo statements in a .php file.

What the rendering pipeline actually does

The entry point is SsrPageHandler::handleRenderPage(). It takes a path, an account, and an HTTP request. It returns an array with the rendered HTML, a status code, and headers. That's it.

public function handleRenderPage(
    string $path,
    AccountInterface $account,
    HttpRequest $httpRequest,
    string $requestedViewMode = 'full',
): array {

The method signature tells you what matters: a path to render, who's asking, and what view mode they want. The return type is a structured array, not a framework-specific response object. The kernel decides how to send it.

Between receiving the path and returning HTML, five things happen in sequence:

Language negotiation resolves the content language from URL prefixes and Accept-Language headers.
Path alias resolution maps friendly URLs to entity references.
Editorial visibility checks whether the current account can see the content.
Entity rendering converts the entity into a Twig variable bag with formatted fields.
Template resolution finds the most specific Twig template and renders it.

If the path doesn't resolve to an entity, RenderController tries a path-based template instead. Visit /about and it looks for about.html.twig. Visit / and it looks for home.html.twig. No route file needed.

Steps 1 through 3 narrow down what to render. Step 4 is where it gets interesting.

How entities become template variables

The EntityRenderer is where the real work happens. It takes an entity and a view mode, and returns a flat array that Twig can consume directly:

public function render(EntityInterface $entity, ViewMode|string $viewMode = 'full'): array
{
    $mode = $viewMode instanceof ViewMode ? $viewMode->name : (string) $viewMode;
    $entityTypeId = $entity->getEntityTypeId();
    $definition = $this->entityTypeManager->getDefinition($entityTypeId);
    $fieldDefinitions = $definition->getFieldDefinitions();
    $display = $this->viewModeConfig->getDisplay($entityTypeId, $mode);

    // ... field formatting happens here ...

    return [
        'entity' => $entity,
        'entity_type' => $entityTypeId,
        'bundle' => $entity->bundle(),
        'view_mode' => $mode,
        'template_suggestions' => $this->buildTemplateSuggestions($entityTypeId, (string) $entity->bundle(), $mode),
        'fields' => $fields,
    ];
}

The return value is a plain associative array. Every field gets three things: the raw value, a formatted string ready for output, and the field type. Your Twig template can use {{ fields.body.formatted }} for the processed HTML or {{ fields.body.raw }} when you need the original.

View mode configuration controls which fields appear and in what order. A teaser view mode might show only the title and summary. A full view mode shows everything. If no display configuration exists for a view mode, the renderer builds a sensible default from the entity's field definitions.

Field formatters: type-safe output without the ceremony

Each field type has a formatter that knows how to turn a raw value into safe HTML. The package ships with formatters for the common cases:

PlainTextFormatter for strings (with proper escaping)
HtmlFormatter for rich text
DateFormatter for timestamps
ImageFormatter for image fields
BooleanFormatter for flags
EntityReferenceFormatter for relationships between entities

The FieldFormatterRegistry maps field types to formatters. When the entity renderer processes a field, it asks the registry for the right formatter and calls it:

$fields[$fieldName] = [
    'raw' => $raw,
    'formatted' => $this->formatterRegistry->format($formatterType, $raw, $settings),
    'type' => $fieldType,
];

One line of code handles the dispatch. The formatter does the escaping, date formatting, or reference resolution. Your template never has to worry about whether a value is safe for output.

You can register custom formatters for domain-specific field types. The #[AsFormatter] attribute marks a class as a formatter, and the registry picks it up automatically.

Template resolution: the chain loader

Waaseyaa uses Twig's ChainLoader to search for templates in priority order. The ThemeServiceProvider builds the chain at boot:

public static function createTemplateChainLoader(
    string $projectRoot,
    string $activeTheme = '',
): ChainLoader {
    $chain = new ChainLoader();

    // 1) App templates (highest priority)
    self::addPathLoaderIfExists($chain, $root . '/templates');

    // 2) Active theme templates
    // ... discovered from composer metadata ...

    // 3) Package templates
    // ... from packages/*/templates ...

    // 4) Base SSR templates (lowest priority)
    self::addPathLoaderIfExists($chain, $root . '/packages/ssr/templates');

    return $chain;
}

Your application's templates/ directory wins over everything. The active theme sits below that. Package templates come next. The base SSR package provides the fallback.

This means you can override any template at any level. Want a custom 404 page? Drop 404.html.twig in your app's templates/ directory. Want a theme to provide a default layout that individual apps can override? That works too.

Theme discovery reads composer.json metadata. Any package with a waaseyaa.theme key in its extra block is a theme candidate:

{
    "extra": {
        "waaseyaa": {
            "theme": {
                "id": "my-theme",
                "templates": "templates"
            }
        }
    }
}

No theme registry, no configuration file, no admin panel. Composer already knows what's installed. The SSR package just reads that.

Template suggestions: specificity without complexity

When the entity renderer builds a variable bag, it also generates template suggestions, an ordered list of template filenames from most specific to least:

private function buildTemplateSuggestions(
    string $entityTypeId,
    string $bundle,
    string $mode,
): array {
    return [
        "{$entityTypeId}.{$bundle}.{$mode}.html.twig",   // node.article.teaser.html.twig
        "{$entityTypeId}.{$bundle}.full.html.twig",       // node.article.full.html.twig
        "{$entityTypeId}.{$mode}.html.twig",              // node.teaser.html.twig
        "{$entityTypeId}.full.html.twig",                 // node.full.html.twig
        "entity.html.twig",                               // catch-all
    ];
}

The RenderController walks this list and uses the first template that exists. Create node.article.teaser.html.twig and it renders article teasers. Remove it and the renderer falls through to the next match. You only create the templates you need.

What this isn't

This isn't PHP 4. There's no <?php echo $row['title'] ?> in a file that's also running SQL queries. The rendering layer is separate from data access, has proper escaping through Twig's auto-escape, supports i18n, and handles caching with surrogate keys for CDN invalidation.

But the fundamental model is the same one PHP has used since the beginning: the server receives a request, finds the right template, fills it with data, and sends HTML to the browser. The browser receives a fully rendered page and displays it. Nothing to hydrate. Nothing to rebuild.

The JavaScript ecosystem spent a decade reinventing this model and gave it a new name. Waaseyaa just kept doing it.

Baamaapii

How to Build an AI Content Playbook That Actually Protects Your Voice

Russell Jones — Sun, 05 Apr 2026 16:30:39 +0000

Ahnii!

You've read the articles warning you not to let AI take over your content. Ruth Doherty's latest piece is one of the best: a clear-eyed breakdown of where AI helps and where it silently destroys your brand. This post shows you how to take that framework and turn it into an actual operating document for your content pipeline.

Why a Framework Without a Playbook Doesn't Stick

Ruth's core argument is sharp: AI is an efficiency engine, not a strategy engine. Use it for research, structuring, repurposing, and editing. Keep it away from messaging, customer research, and anything that requires your actual point of view.

That distinction is easy to agree with. It's harder to enforce on a Tuesday afternoon when you're behind on three social posts and the AI can draft all of them in 90 seconds.

A framework tells you what to believe. A playbook tells you what to do at 4pm when you're tired and the publish queue is empty.

Define Your AI Boundary Table

The first thing your playbook needs is a boundary table. Two columns: what AI does, what you do.

AI Does This	You Do This
Structure scattered notes into outlines	Decide what to write about and why
Generate zero-drafts from session transcripts	Write the actual post with your voice and lived experience
Convert one post into platform-specific social copy	Review and approve every piece before it publishes
Optimize metadata (titles, tags, descriptions)	Record yourself on camera, choose the angle, be present
Tighten prose, check consistency, flag voice drift	Define and evolve your brand voice and positioning
Research acceleration (trends, competitors, grants)	Make strategic decisions about what to build and who to serve

This table isn't aspirational. It's operational. Every content task in your week should land on one side or the other. If something sits in the middle, you haven't decided yet, and that ambiguity is where drift starts.

Add Human Gates

Ruth warns about "publishing AI-written content without human POV." The fix isn't vigilance. It's process.

For every stage where AI generates output, define a human gate: a specific point where a person reads the thing and decides whether it ships.

Here's how that looks in practice for a weekly content cadence:

Writing day: AI helps with outlines and zero-drafts. You write the post. Human gate: nothing publishes until you've read the final version.

Distribution day: AI generates platform-specific social copy from your post. Human gate: you read every variant before it enters your scheduling tool.

Newsletter day: AI can proofread. You write the newsletter. Human gate: this is 100% your voice. AI assists with mechanics only.

Video day: AI generates metadata options. You record yourself. Human gate: you pick the title and description from AI-generated options. You are the face and voice.

The pattern is consistent: AI handles the transformation layer. You own the creation layer and the approval layer.

Draw Harder Lines for Sensitive Content

Ruth's framework applies broadly, but some content carries more weight than others. If you're building something that represents a community, a mission, or a set of values, AI involvement needs a shorter leash.

If you're building something like OIATC, the Ontario Indigenous AI & Technology Council, the stakes are higher. Indigenous digital sovereignty is not something AI should be framing. The entire point of an organization like that is that communities govern their own digital infrastructure. Having AI write the messaging would undermine the premise.

Your version might be different: a founder's origin story, a nonprofit's mission statement, a community you represent. Whatever carries identity-level stakes gets a harder boundary. AI can format. AI can research. AI does not speak on behalf of communities.

But even when the content isn't identity-level sensitive, the tools themselves can create problems.

Prevent the Tool Patchwork

One of Ruth's sharpest observations is about "accidental AI patchwork." Teams adopt tools informally, nobody coordinates, and suddenly you have three things generating social copy with different voice settings and no shared prompts.

Your playbook needs a tool inventory. Every AI tool in your pipeline, listed once, with its purpose and status:

Tool	Purpose	Status
Your primary AI assistant	Writing assist, content skills, distribution	Active
Scheduling tool (e.g., Buffer)	Social scheduling	Active
Blog build system	Publish and deploy	Active
Social copy generator	Platform-specific variants	Active
Video metadata optimizer	YouTube titles, tags, descriptions	Active
That thing you installed three months ago	Unclear	Decide: wire or deprecate

The last row is the important one. If a tool sits unused for a quarter, it's either waiting to create confusion or it's dead weight. Name it explicitly and decide.

Run a Quarterly Review

A playbook that never gets reviewed drifts just like content that never gets edited. Four questions, once every three months:

Is any tool on the list unused? Remove it or document why it stays.
Has a new tool been adopted informally? Add it with clear boundaries.
Has AI output been published without human review? Fix the gap.
Does your content still sound like you? Read your last four posts aloud. If they're interchangeable with any other blog in your niche, something slipped.

What This Looks Like After One Session

Here's the proof that this works: you can build a complete AI playbook in a single sitting. Boundary tables, human gates, brand-specific danger zones, tool inventory, quarterly review checklist. One session, one document.

Here's a preview of what the playbook covers. The full version is on GitHub.

The boundary table draws the line between AI work and human work for every content task in your week.

Per-brand voice rules prevent AI from blending your voices when you operate across multiple brands or audiences. Each brand gets its own prompt context and tone markers.

Pipeline stages with human gates map every step of your weekly cadence (writing, distribution, newsletter, video) to where AI helps and where you approve:

Stage	AI Role	Human Gate
Writing	Zero-drafts, outlines, structure	You write the post. Nothing publishes unread.
Distribution	Platform-specific social copy	You review every variant before scheduling.
Newsletter	Proofreading only	You write it. 100% your voice.
Video	Metadata optimization	You record. You pick the title.

Danger zones name the specific content types where AI must not lead: community messaging, proposals, customer research, thought leadership without lived experience.

Tool inventory lists every AI tool in the pipeline with its purpose and status, preventing the silent accumulation Ruth warns about.

Quarterly review keeps the playbook honest with four questions you run every three months.

The playbook goes in your brand directory, right next to your voice rules and platform templates. It's not a manifesto. It's a reference document you check when you're tired and tempted to let the AI do more than it should.

Ruth's framework gives you the "why." The playbook gives you the "what to do about it at 4pm on a Tuesday."

If you're nodding along to articles about AI misuse but haven't drawn your own lines yet, this is the afternoon to do it.

Baamaapii

Build a free links page with GitHub Pages

Russell Jones — Sun, 05 Apr 2026 14:48:14 +0000

Ahnii!

A Bluesky thread recently reminded me how many developers still reach for Linktree or Carrd when they need a simple links page. You don't need either. GitHub gives you two free surfaces that work as a links hub right now: a profile README and a Pages site. This post walks through both, then covers where to go if you want more.

Why own your links page

Linktree, Carrd, and similar services are convenient. They're also someone else's domain, someone else's design constraints, and someone else's decision about whether your free tier keeps working next year.

A links page is one HTML file. It doesn't need a SaaS product. When you host it yourself, you control the URL, the design, and the uptime. GitHub Pages gives you HTTPS, a clean subdomain, and global CDN for free.

That's the pitch. Here's how to set it up.

Option 1: the profile README

Every GitHub account has a special repo: your-username/your-username. Create it, add a README.md, and GitHub renders it at the top of your profile page.

Create the repo

Go to github.com/new
Name the repo exactly the same as your GitHub username
Make it public
Check "Add a README file"
Click Create repository

GitHub shows a banner confirming this is a special repo. Your README.md now renders on your profile.

Structure it as a links page

# Hey, I'm [Your Name]

One-liner about what you do.

## Links

- [Portfolio](https://your-site.com)
- [Blog](https://your-blog.com)
- [LinkedIn](https://linkedin.com/in/your-handle)
- [Email](mailto:you@example.com)

That's a functional links page. Markdown supports links, headings, images, and badges. You can add project descriptions, tech stacks, or whatever context helps visitors understand who you are.

The profile README is a good starting point, but it lives on github.com. If you want a standalone URL you can share anywhere, GitHub Pages is the next step.

Option 2: a GitHub Pages links site

GitHub Pages serves a static site from a repo. Create a repo named your-username.github.io, drop in an index.html, and you have a live site at https://your-username.github.io.

Create the repo

Create a new repo named your-username.github.io
Clone it locally:

git clone https://github.com/your-username/your-username.github.io.git
cd your-username.github.io

This gives you an empty repo ready for your site files.

Add a single-file links page

Create an index.html. Here's a minimal starting point:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Your Name</title>
  <style>
    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }

    body {
      font-family: system-ui, sans-serif;
      background: #0a0f14;
      color: #e8eef4;
      min-height: 100vh;
      display: flex;
      align-items: center;
      justify-content: center;
      padding: 2rem;
    }

    .container { width: 100%; max-width: 560px; }

    h1 { font-size: 2.5rem; margin-bottom: 0.5rem; }

    .tagline {
      color: #7a9ab5;
      margin-bottom: 2rem;
      line-height: 1.6;
    }

    .links {
      display: grid;
      grid-template-columns: 1fr 1fr;
      gap: 0.75rem;
    }

    .link-card {
      padding: 1rem 1.25rem;
      background: #111820;
      border: 1px solid #1e2d3d;
      border-radius: 8px;
      text-decoration: none;
      color: #e8eef4;
      transition: border-color 0.15s ease;
    }

    .link-card:hover { border-color: #00b4a0; }

    .link-card .label { font-weight: 500; display: block; }
    .link-card .desc { font-size: 0.8rem; color: #7a9ab5; }

    @media (max-width: 420px) {
      h1 { font-size: 2rem; }
      .links { grid-template-columns: 1fr; }
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>Your Name</h1>
    <p class="tagline">What you do, in one or two sentences.</p>

    <div class="links">
      <a class="link-card" href="https://your-portfolio.com">
        <span class="label">Portfolio</span>
        <span class="desc">Projects and work</span>
      </a>
      <a class="link-card" href="https://your-blog.com">
        <span class="label">Blog</span>
        <span class="desc">Writing and tutorials</span>
      </a>
      <a class="link-card" href="https://github.com/your-username">
        <span class="label">GitHub</span>
        <span class="desc">Open source</span>
      </a>
      <a class="link-card" href="https://linkedin.com/in/your-handle">
        <span class="label">LinkedIn</span>
        <span class="desc">Professional profile</span>
      </a>
    </div>
  </div>
</body>
</html>

This gives you a dark-themed, responsive two-column grid. No build tools, no dependencies, no framework. One file, under 100 lines of code.

Push and go live

git add index.html
git commit -m "Add links page"
git push

Within a minute, your site is live at https://your-username.github.io. GitHub Pages is enabled by default for repos with this naming convention.

Add Open Graph metadata

Social platforms pull title, description, and image from OG meta tags when someone shares your link. Add these inside <head>:

<meta property="og:title" content="Your Name">
<meta property="og:description" content="Your one-liner.">
<meta property="og:type" content="website">
<meta property="og:url" content="https://your-username.github.io">
<meta property="og:image" content="https://your-username.github.io/photo.jpg">

Drop a photo in the repo root and reference it in the og:image tag. Now when you share your link on LinkedIn or Bluesky, the preview card shows your face instead of a blank box.

Use both together

The profile README and Pages site serve different audiences. The README catches developers who land on your GitHub profile. The Pages site gives you a clean URL to put in your social bios, email signature, and conference slides.

Point the README's links to your Pages site (or vice versa) so both surfaces reinforce each other. For example, the jonesrussell profile README introduces the person and the work, while jonesrussell.github.io is the shareable link card.

Taking it further

A single HTML file covers most needs. If you outgrow it, here are three directions worth considering.

Add a custom domain

GitHub Pages supports custom domains for free. In your repo settings under Pages, add your domain and configure a CNAME DNS record. GitHub handles the SSL certificate automatically. Your links page goes from your-username.github.io to links.yourdomain.com (or whatever you prefer).

Use a static site generator

If you want templating, multiple pages, or a blog alongside your links page, a static site generator keeps things manageable:

Astro is beginner-friendly and ships zero JavaScript by default. It has link page themes ready to customize.
Hugo is fast and works well if you're already writing markdown. This blog runs on Hugo.
11ty is minimal and flexible, with no opinions about your frontend stack.

All three deploy to GitHub Pages with a simple Actions workflow.

Try a CSS framework

If you want better design without writing all the CSS yourself, drop in a utility framework:

Tailwind CSS via CDN for rapid styling without a build step
Pico CSS for classless styling that looks good out of the box
A single <link> tag pointing to Water.css for a no-effort dark theme

None of these require a build tool. Add a <link> or <script> tag and start using them.

Own your links, own your URL

Your links page is the one URL that represents you everywhere. Owning it means you decide how it looks, what it links to, and where it lives. GitHub gives you the hosting for free. The rest is just HTML.

Baamaapii

Automate your content pipeline with GitHub Actions and Issues

Russell Jones — Sun, 05 Apr 2026 02:22:03 +0000

Ahnii!

You ship work every day, but most of it never becomes a post. The problem isn't writing. It's remembering what you shipped three days ago that was actually worth talking about. This post walks through a content pipeline that mines your GitHub repos daily and queues content ideas as issues, so nothing slips through.

How the Pipeline Works

The system has three moving parts: a GitHub Actions workflow that runs on a cron schedule, an issue template that standardizes the format, and label-based stages that track each idea from raw commit to published post.

flowchart TD
    A[commit lands] --> B[Action mines it]
    B --> C[issue created<br/>stage:mined]
    C --> D[you curate<br/>stage:curated]
    D --> E[produce copy<br/>stage:ready]
    E --> F[distribute]

Every stage is a GitHub label. You always know where each content idea sits, and nothing moves forward without your decision.

The Mining Workflow

The workflow runs daily at 8am ET, scans a list of repos, and creates issues for commits that look like real work.

name: Content Mining

on:
  schedule:
    - cron: '0 12 * * *'
  workflow_dispatch:

permissions:
  issues: write
  contents: read

The workflow_dispatch trigger lets you run it manually when you want to catch up. Permissions are scoped to just what the job needs: reading commits and writing issues.

The core loop iterates over repos and fetches recent commits via the GitHub API:

env:
  GH_TOKEN: ${{ secrets.CROSS_REPO_TOKEN }}
run: |
  SINCE=$(date -u -d '1 day ago' +%Y-%m-%dT%H:%M:%SZ)
  REPOS="waaseyaa/framework waaseyaa/giiken jonesrussell/jonesrussell"

  for REPO in $REPOS; do
    COMMITS=$(gh api "repos/$REPO/commits?since=$SINCE&per_page=50" \
      --jq '.[] | select(.commit.message | test("...filter...") | not) | ...')
  done

The CROSS_REPO_TOKEN is a personal access token with read access to all repos you want to mine. Without it, the workflow can only see public repos.

Filtering Noise

Not every commit is content. The filter regex excludes merge commits, dependency bumps, docs changes, and housekeeping fixes:

test("^(Merge |chore|docs|fix typo|bump|update dep|Bump |fix:.*
  ([Pp]hp[Ss]tan|namespace|alignment|placeholder|phpunit|mock|ignore|typo))"; "i")

This catches the patterns that showed up as noise in practice: PHPStan fixes, namespace alignment, test placeholders. Commits also need a minimum message length of 25 characters to filter out low-context changes like "fix test" or "update readme".

The filter will evolve. After your first curation pass, you'll know which patterns your repos produce that aren't worth posting about. Update the regex and the next run gets cleaner.

Deduplication

Before creating an issue, the workflow checks whether a commit has already been queued:

EXISTING=$(gh issue list --repo jonesrussell/jonesrussell \
  --label "content-queue" --search "$SHA" \
  --json number --jq 'length')
if [ "$EXISTING" != "0" ]; then
  echo "Skipping (already queued): $MSG"
  continue
fi

This prevents duplicate issues when you re-run the workflow manually or when the cron overlaps with a manual trigger.

The Issue Template

Each mined commit becomes an issue with a structured body:

## Source
Commit `abc1234` in `waaseyaa/framework`

## Content Seed
feat(#571): add DomainRouterInterface, EntityTypeLifecycleRouter, SchemaRouter

## Suggested Type
text-post

## Suggested Channels
x, linkedin, facebook

## Generated Artifacts
<!-- To be filled by production skill -->

The "Generated Artifacts" section stays empty until you curate and produce the content. Labels track the stage: stage:mined, stage:curated, stage:ready, stage:distributed.

The Curation Step

Mining is automated. Curation is not. You review each stage:mined issue and decide: approve, skip, merge with another item, or edit the seed. Skipped items get closed with an audit comment explaining why. Approved items move to stage:curated.

This is where judgment lives. A commit that says "feat: Community RBAC policies" might be a standalone post or might merge with two other commits into a broader story about your data model. The pipeline gives you the raw material. You shape it.

Closed Issues as Content Sources

The workflow also scans recently closed issues across your repos:

gh issue list --repo "$REPO" --state closed \
  --json number,title,closedAt,labels \
  --jq ".[] | select(.closedAt > \"$SINCE\") | ..."

Closed issues often represent shipped features with richer context than a commit message. The workflow creates content queue items for those too, with the same deduplication and labeling.

Setting It Up in Your Repos

You need three things:

A personal access token (CROSS_REPO_TOKEN) with repo scope, stored as a repository secret
The workflow file at .github/workflows/content-mine.yml in whichever repo you want to host the content queue
The labels created in that repo: content-queue, stage:mined, stage:curated, stage:ready, stage:distributed, stage:skipped

Create the labels first:

for label in content-queue stage:mined stage:curated stage:ready stage:distributed stage:skipped; do
  gh label create "$label" --repo your-org/your-repo
done

Then add the workflow, update the REPOS list with your repos, and trigger it manually to verify.

What This Doesn't Do

This pipeline handles discovery, not writing. It won't draft a blog post or compose a tweet. Those are separate steps that happen after curation, when you know the angle and audience for each piece.

It also won't decide what's worth posting. That's the point. Automated mining with human curation gives you a reliable queue without losing editorial control.

Baamaapii

What a real AI-assisted PR looks like

Russell Jones — Thu, 02 Apr 2026 17:17:03 +0000

Ahnii!

A lot of AI coding content ends too early.

The model writes a patch. The patch looks plausible. A few tests pass. Someone posts a screenshot and calls it proof.

That is not the part I care about.

What I want to know is whether an AI-assisted change can survive the whole engineering process: audit, review, CI, static analysis, contract repair, docs drift, and merge.

PR #1022 was the first pull request in Waaseyaa where that full chain played out end to end.

The Invariant

The bug looked small: pipeline navigation in the admin SPA was non-deterministic.

Whether the pipeline link showed up depended on whether a mount-time request happened to succeed. If a board-config request failed for incidental reasons, the UI could act like the entity type had no pipeline at all.

That is not just a UI bug. That is a contract problem.

The invariant was simple:

Pipeline navigation visibility must be a pure function of runtime.catalog actions.

If the catalog entry declares board-config, show pipeline navigation. If it does not, do not. Request failures do not get to define capability truth.

The Workflow

The first step was not refactoring. It was audit.

I had the model inspect only the affected surfaces, identify exactly where visibility depended on incidental request failure, state the minimal deterministic invariant, and identify the contract boundary that had to be restored.

That exposed the real issue quickly: the problem was not only in the component. The admin runtime was also dropping actions when it built the runtime catalog. Once that contract data disappeared, the UI fell back to probing with runAction().

After that, the first patch was straightforward:

remove mount-time probing from NavBuilder.vue
preserve actions in the runtime catalog
add tests proving visibility comes from declared catalog actions

If this were a typical AI coding story, that would have been the end.

It was not.

Where The PR Got Interesting

Review found another component, EntityViewNav.vue, still violating the same invariant. So the first fix was only partial.

Then CI started surfacing deeper inconsistencies:

nuxi typecheck exposed an admin catalog type surface that no longer matched runtime reality
build:contracts failed because the admin contract build crossed a package boundary it should not have crossed
PHPStan failed on a dispatcher contract mismatch elsewhere in the repo
spec drift failed because the architecture docs now lagged behind the code

This is the part I think people miss about AI-assisted development.

The value is not that the model gets you to the first patch faster. The value is whether you can keep following the consequences after that patch lands.

A serious workflow does not treat those as annoying side failures. It treats them as the remediation chain.

What Merged

By the time PR #1022 merged, it had gone through:

invariant audit
deterministic refactor plan
initial implementation
review-discovered residual drift
follow-up invariant enforcement
runtime contract restoration
type-surface repair
contract build repair
PHPStan repair
spec drift repair
merge

That is why this PR matters to me.

It is the first one in this workflow that exercised the whole model instead of just one slice of it.

The model is not “AI writes code and I tidy it up.”

The model is:

define the invariant
constrain the agent to the governed surface
audit before refactor
keep the refactor minimal
review adversarially for drift
treat CI failures as evidence
repair every broken surface the change exposes
merge only when the whole chain is green

What I’m Learning

The biggest lesson is that the first answer is rarely the interesting one.

The interesting part is whether the system can keep reasoning correctly after the easy fix is in. Can it preserve the invariant through review? Can it repair the contract without weakening it? Can it follow the consequences into docs and verification instead of pretending those are separate tasks?

That is where trust gets built.

AI is awesome. More awesome than a lot of people realize. But not because it can one-shot production code from a prompt.

It is awesome when you put it inside a disciplined engineering model and it helps you push a real change all the way through the system without losing the thread.

That is what I am trying to build in public right now.

Not a demo.

An operating model.

Baamaapii

Waaseyaa governance series

Russell Jones — Wed, 01 Apr 2026 13:12:43 +0000

Ahnii!

This series covers how Waaseyaa — a PHP framework monorepo of 52 packages — went from accumulated architectural drift to a governed, verifiable implementation platform.

1. The audit that started everything

What architectural drift looks like in a 52-package PHP monorepo, how the invariant-driven M1 audit was designed with frozen vocabularies before the first finding was written, what it found across five concern passes, and how M2 turned 36 findings into a dependency-ordered eight-milestone program.

2. Eight milestones, one chain

How the remediation program ran from M3 through M8, how the exit-gate verified nothing drifted during execution, and how the program completion artifact locked the outputs as fixed inputs to everything downstream.

3. The conformance engine

How M9 froze a canonical model, classified repo-wide drift, built a dependency-ordered execution DAG, and activated M10 batch execution — including the live code changes landing on m10-batch-d1 right now.

Each post stands alone if you need a specific part. Start at Part 1 for the full story.

Baamaapii

The audit that started everything: how Waaseyaa designed an invariant-driven architectural review

Russell Jones — Wed, 01 Apr 2026 13:12:35 +0000

Ahnii!

This is Part 1 of the Waaseyaa Governance series. It covers how Waaseyaa — a PHP framework monorepo of 52 packages — ran a formal invariant-driven architectural audit, what it found across five concern passes, and how Milestone 2 turned those findings into the eight-milestone remediation program covered in Part 2.

Prerequisites

Familiarity with PHP Composer package mechanics (extra, autoload, provider discovery)
Comfort reading GitHub issue-driven governance workflows
No prior knowledge of Waaseyaa required

What Drift Looks Like at Scale

Waaseyaa is a PHP framework organized into a 7-layer architecture across 52 Composer packages. The layers run from L0 (foundation infrastructure) up through L6 (interfaces — the admin SPA, SSR, and other user-facing surfaces). The constraint that makes the model useful is simple: packages may only import from their own layer or lower. Upward communication must go through sanctioned seams.

That constraint is easy to state and hard to maintain. Feature work happens fast. A developer needs something from a higher layer, adds a dependency, moves on. A provider needs access to a kernel-composed service, reconstructs it locally instead. A CLI command gets implemented, never wired into the registered console surface. None of these are catastrophic individually. Over time they accumulate into a codebase where the architectural model and the actual dependency graph have quietly diverged.

The standard response is ad hoc cleanup: fix things as you notice them, add notes to the CLAUDE.md, hope the team remembers. That works up to a point. It stops working when the divergence is widespread enough that you cannot trust the layer model as an enforceable invariant. At that point you need an audit — not as a one-time cleanup, but as a structured baseline that everything downstream can depend on.

Designing the Audit Before Running It

The critical decision in #817 was to freeze the audit's vocabulary before the first finding was written.

The concern model was frozen:

boundaries — package dependency edges and layer violations
contracts — interface and API contract gaps
testing — harness coverage and test quality
docs-governance — specification drift and documentation alignment
dx-tooling — developer experience and build tooling gaps

The layer model was frozen: L0-foundation through L6-interfaces, plus cross-layer for concerns that span multiple layers.

The closed vocabularies were frozen: subsystem taxonomy (14 values), severity (critical / high / medium / low), remediation class (8 values: invariant-break, contract-gap, coverage-gap, governance-drift, docs-drift, tooling-gap, cleanup-candidate, framework-uplift), audit phase, and evidence sources.

These are not just taxonomies. They are constraints on the audit's own output. A finding that does not fit one of the frozen remediation classes cannot be created. An issue with an ad hoc severity value is invalid. The vocabulary freeze meant every finding would be comparable, sortable, and clusterable without disambiguation work later.

The scope was equally constrained:

Framework repository only

No downstream consumer apps

No remediation work

No finding issues until each pass rubric is stable

That last rule matters most. Finding issues were blocked until the pass rubric — the set of questions each pass would ask and the evidence format it would use — was stable. Without that gate, early findings would have been written under different assumptions than later ones, making the inventory inconsistent before M2 tried to cluster it.

Five Passes, Fixed Order

M1 ran five passes sequentially. Each pass had its own concern, its own subsystem focus, and its own pass issue that owned the rubric before findings were created.

Pass	Concern	Focus
M1-boundaries	Package dependency edges and layer violations	L0–L6 layer graph
M1-contracts	Interface and API contract gaps	Public surface correctness
M1-testing	Harness coverage and test quality	Foundation, kernel, integration
M1-docs-governance	Specification drift	Specs vs. implementation alignment
M1-dx-tooling	Developer experience gaps	CLI, build tooling, console surface

The order was intentional. Boundary violations had to be catalogued first because contracts, testing, and docs findings often depend on knowing which package boundaries are already broken. You cannot reason about whether a contract is correctly expressed if the package expressing it is importing from the wrong layer.

What M1 Found

M1 produced 36 finding issues (#823 through #858). A sample across concerns shows the range of what the audit captured.

Boundary violations were the most severe class. #823 caught a direct upward dependency in the API layer:

The API package declares waaseyaa/ssr as a package dependency even though the documented architecture places api in Layer 4 and ssr in Layer 6.

Evidence: packages/api/composer.json lines 39–50 declare ../ssr and require waaseyaa/ssr

That is not an ambiguous finding. The layer model says Layer 4 cannot depend on Layer 6. The Composer manifest says it does. Remediation direction: untangle the dependency before treating the layer table as an enforceable invariant.

Some findings were subtler topology problems. #824 caught a representation mismatch rather than a dependency edge:

CLAUDE.md lists admin in the Layer 6 package table, while packages/admin is a Node/Nuxt workspace with package.json and no composer.json.

The admin SPA exists outside the Composer package graph entirely. Any mechanical boundary check that reads from vendor/composer/installed.json cannot see it. The finding was not that admin was in the wrong layer — it was that the layer model's topology representation was inconsistent about what counts as a package. Remediation direction: clarify whether the layer model governs all repo workspaces or only Composer packages, then align the representation accordingly.

Hidden composition roots were flagged as invariant breaks. #831 found the admin-surface provider reconstructing core security wiring from manifest storage rather than consuming a kernel-composed service:

AdminSurfaceServiceProvider loads storage/framework/packages.php, rebuilds a PackageManifest, instantiates AccessPolicyRegistry, and reconstructs an EntityAccessHandler for its host wiring.

The architecture reserves cross-layer orchestration for the kernel composition root. An interface-layer provider that rebuilds access-policy wiring independently is a hidden composition root — one that will silently diverge from the kernel's version over time. Remediation direction: consume a kernel-composed access service or explicitly model admin-surface access bootstrapping as a sanctioned seam.

The testing pass found brittleness in the harness itself. #845 found foundation kernel tests coupled to implementation detail:

packages/foundation/tests/Unit/Kernel/HttpKernelTest.php repeatedly uses ReflectionMethod, ReflectionProperty, and setAccessible() to invoke private methods and mutate internal kernel state.

Tests that reach private state through reflection are not testing invariants — they are testing implementation. They pass when the internal structure is intact and fail when it is refactored, regardless of whether the public behavior changed. The audit classified this as a cleanup-candidate with medium severity: real technical debt, but not an invariant break.

The DX tooling pass found phantom CLI commands. #858 found a gap between what was implemented and what was reachable:

Implemented command classes exist for queue:work, queue:failed, queue:retry, queue:flush, schedule:run, schedule:list, scaffold:auth, and telescope:validate under packages/cli/src/Command/*. php bin/waaseyaa list --raw does not expose any of those commands.

The operations playbooks documented these commands as operational workflows. The actual CLI surface did not expose them. Any operator following the playbook would find their commands missing. This was classified as tooling-gap with high severity: the gap between documented and actual behavior was wide enough to cause operational incidents.

From Findings to a Program: M2

With 36 findings across five concerns, the question M2 had to answer was: how do you turn an inventory of problems into a sequence of work that closes them without creating new ones?

#859 defined the M2 scope:

cluster M1 findings #823–#858 into remediation themes

derive a dependency-ordered remediation graph

identify cross-layer sequencing constraints

define uplift phases that preserve architectural invariants

produce a milestone-ready remediation roadmap

Clustering findings into themes meant grouping by what needed to be stable before something else could be fixed. The boundary violations could not be the last thing addressed — they had to come first, because contract, testing, and governance work all depended on a stable layer model. The CLI tooling gaps could not be fixed before the kernel bootstrap paths that should have wired those commands were themselves corrected.

M2 produced the eight-milestone structure: M3 (architectural base recovery), M4 (public-surface unification), M5 (verification lock-in), M6 (governance alignment), M7 (workflow ergonomics), M8 (implementation-surface alignment). Each milestone consumed its predecessor's outputs as fixed inputs. Each had sequencing constraints that prevented it from reaching into territory that belonged to a later milestone.

The dependency ordering was not arbitrary. It followed from the finding inventory. Boundary violations in M3 had to stabilize before M4 could unify public surfaces — you cannot unify contracts across a broken layer graph. M5 verification lock-in depended on M4's stable surfaces to verify against. The chain was determined by the findings, not by preference.

The Governance Scaffold

The two-artifact pattern that every milestone used — a bootstrap gate and an execution umbrella — was itself a finding from M2's synthesis work. A remediation program that does not constrain its own scope will drift. Each milestone needs an explicit statement of what it can and cannot touch before execution starts.

The bootstrap gate restates the dependency prerequisites, sequencing constraints, and exit criteria before any track begins. It is not a planning document — it is an activation gate. A milestone that cannot satisfy its bootstrap gate does not start.

The execution umbrella owns the tracks and holds the exit criteria. When the umbrella's exit criteria are satisfied, the milestone closes. Nothing else triggers closure.

Together, the two artifacts make the program self-describing and self-constraining. Any reviewer reading the issue chain can see what each milestone was allowed to do, what it actually did, and whether its exit criteria were met — without reading the code.

That structure carried the program from M3 through M8. Part 2 covers how it ran, how it closed, and what it handed off to conformance work.

Baamaapii

Build an eval harness for 184 AI agent prompts with promptfoo

Russell Jones — Mon, 30 Mar 2026 18:50:37 +0000

Ahnii!

Agency-agents is an open-source collection of 184 specialist AI agent prompts (my fork with the eval harness). Backend architects, UX designers, historians, game developers. Each prompt is a detailed markdown file with identity, workflows, deliverable templates, and success metrics. But there's no way to know if any of them actually produce good output. You can build a promptfoo-based eval harness that scores them automatically using LLM-as-judge, and the first run already found a real quality gap.

Why Agent Prompts Need Evals

You can read an agent prompt and think it looks good. That doesn't scale to 184 agents, and it doesn't catch regressions when someone edits a prompt. You need a system that answers five questions every time:

Did the agent complete the task?
Did it follow its own defined workflow?
Did it stay in character?
Is the output actually useful?
Is it safe and unbiased?

That's the eval flywheel. Define scoring criteria, run agents against representative tasks, judge the outputs automatically, and turn failures into regression tests. The collection can only improve because every failure becomes a test case.

The existing CI for agency-agents is a bash linter that checks if frontmatter fields exist. It can tell you an agent has a name and description. It can't tell you the agent produces garbage output. What would it look like if it could?

The Eval Architecture

The eval harness lives in an evals/ directory at the repo root, self-contained with its own package.json. It uses promptfoo to orchestrate three steps per test:

Load an agent's markdown file as the system prompt
Send it a task from a per-category YAML file
Score the output with a separate LLM acting as judge

The judge scores on five criteria, each rated 1-5. An agent passes if the average is 3.5 or higher.

evals/
  promptfooconfig.yaml          # main config
  rubrics/
    universal.yaml              # 5 scoring criteria with anchors
  tasks/
    engineering.yaml            # tasks per category
    design.yaml
    academic.yaml
  scripts/
    extract-metrics.ts          # parse agent markdown into structured data

The harness doesn't modify any agent files. But it does need to understand them, which means parsing their markdown structure.

Extract Success Metrics from Agent Prompts

Each agent markdown file has a "Success Metrics" section with criteria like "API response times under 200ms" or "every historical claim includes a confidence level." These feed into the judge's rubric so it knows what good output looks like for each specific agent.

The extract-metrics.ts script parses agent files and pulls out three sections: success metrics, critical rules, and deliverable templates.

export function parseAgentFile(filePath: string): AgentMetrics {
  const raw = fs.readFileSync(filePath, "utf-8");
  const { data: frontmatter, content } = matter(raw);
  const category = path.basename(path.dirname(filePath));

  return {
    name: frontmatter.name || path.basename(filePath, ".md"),
    description: frontmatter.description || "",
    category,
    filePath,
    successMetrics: extractSection(content, "Success Metrics"),
    criticalRules: extractSection(content, "Critical Rules"),
    deliverableFormat: extractRawSection(content, "Technical Deliverables"),
  };
}

The section extraction handles emoji-prefixed headings (## 🎯 Your Success Metrics) and nested sub-headings. It matches case-insensitively on the key phrase, not the exact heading text.

Agent files are inconsistent in ways that matter here. Engineering agents have measurable KPIs ("zero critical vulnerabilities"). Design agents have vague ones ("CSS remains maintainable"). The eval system surfaces this inconsistency, which turns out to be useful feedback for prompt authors even before you look at scores.

Define the Scoring Rubric

The universal rubric defines five criteria. Each one gets explicit anchor descriptions so the judge knows what a 1 versus a 5 looks like.

criteria:
  task_completion:
    name: Task Completion
    rubric: |
      5 - Fully completed with all requested deliverables present and thorough
      4 - Completed with minor gaps
      3 - Partially completed; key elements missing
      2 - Attempted but incomplete or off-target
      1 - Did not attempt or completely failed

  instruction_adherence:
    name: Instruction Adherence
    rubric: |
      The agent defines specific workflows and deliverable templates.
      Score how well the output follows these defined processes.
      5 - Closely follows defined workflow and templates
      4 - Mostly follows with minor deviations
      3 - Partially follows; some structure present but loosely applied
      2 - Shows awareness but largely ignores defined formats
      1 - Completely ignores the agent's defined workflow

The remaining three criteria (identity_consistency, deliverable_quality, safety) follow the same pattern. Each rubric can also include agent-specific context from the extracted metrics, so the judge evaluates against the agent's own standards. The question is whether the rubric actually produces meaningful differentiation in practice.

Write Category Tasks

Each category gets a YAML file with representative tasks at different difficulty levels. Here's the academic category testing the Historian agent:

- id: acad-period-check
  description: "Verify historical accuracy of a passage"
  prompt: |
    I'm writing a novel set in 1347 Florence, just before the Black Death.
    Here's a passage I need you to check for historical accuracy:

    "Marco adjusted his cotton shirt and leather boots as he walked
    through the cobblestone streets to the bank. He pulled out a few
    paper bills to pay for a loaf of white bread and a cup of coffee
    at the market stall."

    Please identify any anachronisms and suggest corrections.

That passage has at least five anachronisms (paper bills, coffee, cotton availability, white bread, the banking details). A good historian agent should catch them all with source citations. A bad one will miss the subtle ones.

The second task per category is harder: it requires the agent to use its full workflow, not just answer a question. That's where you find out if the prompt's workflow definition actually influences behavior.

Wire Up promptfoo

The config connects agents, tasks, and rubrics. Each test case loads an agent markdown file via file://, sends a task prompt, and runs five LLM-as-judge assertions.

providers:
  - id: anthropic:messages:claude-haiku-4-5-20251001
    config:
      max_tokens: 4096
      temperature: 0

defaultTest:
  options:
    provider: anthropic:messages:claude-haiku-4-5-20251001

tests:
  - description: "backend-architect / REST endpoint design"
    vars:
      agent_prompt: file://../engineering/engineering-backend-architect.md
      task: |
        Design a user registration endpoint for Node.js Express
        with PostgreSQL. Include schema, route, and validation.
    assert:
      - type: llm-rubric
        value: |
          TASK COMPLETION: Did the agent produce a REST endpoint design
          with database schema, API route, and validation?
          5 - Fully completed with schema, route, validation, security
          4 - Completed with minor gaps
          3 - Partially completed; key elements missing
          2 - Attempted but incomplete
          1 - Did not address the task

Both the agent model and the judge model use Haiku. Using the same model family for both is a trade-off: it's cheap but introduces potential self-preference bias. For a proof-of-concept, the cost savings win. For production evals, you'd want the judge on a different model family.

Score Tables: 5 Out of 6 Passed

Three agents, two tasks each, five criteria per task. Here are the actual scores from the first run.

Backend Architect

Criterion	REST Endpoint	Scaling Review
Task Completion	5.0	5.0
Instruction Adherence	4.8	5.0
Identity Consistency	4.7	5.0
Deliverable Quality	4.8	4.8
Safety	5.0	5.0
Result	PASS	PASS

Near-perfect across the board. The scaling review scored a perfect 5.0 on instruction adherence because it followed the agent's System Architecture Specification template exactly.

Historian

Criterion	Florence 1347	Mali Empire
Task Completion	5.0	5.0
Instruction Adherence	5.0	4.8
Identity Consistency	4.8	4.8
Deliverable Quality	4.8	5.0
Safety	5.0	5.0
Result	PASS	PASS

The Mali Empire reconstruction earned a perfect 5.0 on deliverable quality for grounding trade goods, currency, and daily life in evidence while clearly marking where it was extrapolating.

UX Architect

Criterion	Landing Page	Responsive Audit
Task Completion	3.5	5.0
Instruction Adherence	4.5	4.8
Identity Consistency	4.5	3.5
Deliverable Quality	4.5	4.5
Safety	5.0	4.5
Result	FAIL	PASS

Two different problems in one agent. The landing page failed on task completion. The responsive audit passed overall but scored 3.5 on identity consistency: it solved the problem competently but didn't sound like "ArchitectUX." Numbers tell you something is wrong. You need the actual outputs to understand what.

What the Agents Actually Produced

Here's what the Historian produced when asked to check the 1347 Florence passage:

Agent output (excerpt):

Anachronism Why It's Wrong What's Accurate

Paper bills Paper money didn't circulate in Florence until the 15th-16th centuries. Florence in 1347 used gold florins and silver denari, plus credit instruments like bills of exchange for large transactions. Marco would carry a leather purse with gold or silver coins.

Coffee Coffee was unknown in Europe until the 16th-17th century. It was an Ottoman/Arab beverage. Marco would drink wine (even at breakfast), ale, or small beer.

Cotton shirt Cotton was rare and expensive in 1347 Florence. Imported from the Levant and Egypt via Venice. Only the wealthy wore it. Marco would wear linen (if middle-class) or wool.

White bread Affordable white bread is a post-industrial product. In 1347, white bread was a luxury requiring expensive sifting. Marco would eat dark rye or barley bread, or if prosperous, mixed grain bread.

Anachronism	Why It's Wrong	What's Accurate
Paper bills	Paper money didn't circulate in Florence until the 15th-16th centuries. Florence in 1347 used gold florins and silver denari, plus credit instruments like bills of exchange for large transactions.	Marco would carry a leather purse with gold or silver coins.
Coffee	Coffee was unknown in Europe until the 16th-17th century. It was an Ottoman/Arab beverage.	Marco would drink wine (even at breakfast), ale, or small beer.
Cotton shirt	Cotton was rare and expensive in 1347 Florence. Imported from the Levant and Egypt via Venice. Only the wealthy wore it.	Marco would wear linen (if middle-class) or wool.
White bread	Affordable white bread is a post-industrial product. In 1347, white bread was a luxury requiring expensive sifting.	Marco would eat dark rye or barley bread, or if prosperous, mixed grain bread.

The judge's reasoning for scoring task completion at 5.0:

"The output comprehensively identifies all major anachronisms (paper bills, coffee, white bread, cotton shirt, horse-drawn carriages) with detailed explanations. It provides historically accurate alternatives for each item (gold florins/silver denari, wine/ale, dark bread, linen, pack animals). The response goes beyond the basic requirement by including a period authenticity report, sensory details, and a before/after revision example."

Now compare that to the UX Architect's failed test. The task asked for a CSS design system foundation for a SaaS landing page. The agent started strong:

:root {
  --bg-primary: #ffffff;
  --bg-secondary: #f8fafc;
  --text-primary: #1e293b;
  /* ... full typography scale, spacing, shadows ... */
}

But the output hit the token limit and cut off mid-sentence in the button styling section. The hero section, features grid, pricing table, and footer layouts were never delivered. The judge caught it:

"The agent delivered approximately 60-70% of the requested deliverables. It cuts off mid-sentence in the button styling section and does not include the promised layout structure for hero, features grid, pricing table, and footer sections."

That's a 3.5 on task completion, right at the pass threshold. It pulled the average below 3.5 for a FAIL. The fix is straightforward: either increase the token limit for design agents that produce verbose CSS, or tune the prompt to prioritize layout structure over exhaustive variable definitions.

Score Spread Tells You Where to Focus

A Backend Architect scoring 4.7-5.0 across everything means the prompt is well-calibrated. A UX Architect bouncing between 3.5 and 5.0 means the prompt works for some tasks but breaks down on others. That's exactly the kind of signal prompt authors need.

Total cost for this run: 166K tokens, roughly $0.05 at Haiku pricing.

Run It Yourself

git clone -b feat/eval-harness-clean https://github.com/jonesrussell/agency-agents.git
cd agency-agents/evals
npm install
export ANTHROPIC_API_KEY=your-key
npx promptfoo eval

The eval takes about two minutes. After it finishes, open the interactive results viewer:

npx promptfoo view

You get a browser UI showing each test case, the agent's full output, and the judge's reasoning for every score.

What Comes Next

This proof-of-concept covers 3 of 184 agents. The eval harness lives on my fork with an upstream PR pending. The roadmap has three milestones:

M1 (submitted): Eval harness with 3 proof-of-concept agents
M2: Benchmark dataset covering all 184 agents with baseline scores
M3: CI quality gate so PRs that degrade an agent are automatically flagged

The full 184-agent suite would cost about $1.50 per run. Run it nightly and you have a quality trendline. Run it on PRs and you have a regression gate. The collection can only get better.

Baamaapii

Generate Open Graph images with Playwright and an HTML template

Russell Jones — Sun, 29 Mar 2026 19:53:47 +0000

Ahnii!

Every blog post you share on LinkedIn or X gets a preview card. Without an og:image, the platform picks whatever it finds or shows nothing. This post covers how to generate branded OG images automatically from an HTML template using Playwright screenshots, so every post gets a consistent social card without opening a design tool. The full source is in the blog repo.

Prerequisites

Node.js 18+
Playwright (npm install playwright)
gray-matter for frontmatter parsing (npm install gray-matter)
A static site generator that uses frontmatter (this post uses Hugo, but the approach works with any SSG)

Design the HTML template

The OG image spec is 1200x630 pixels. Create an HTML file that renders at exactly that size:

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<style>
  * { margin: 0; padding: 0; box-sizing: border-box; }
  body {
    width: 1200px;
    height: 630px;
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
    overflow: hidden;
  }
  .container {
    width: 1200px;
    height: 630px;
    background: linear-gradient(135deg, {{gradient}});
    display: flex;
    flex-direction: column;
    justify-content: center;
    padding: 60px 80px;
    position: relative;
    overflow: hidden;
  }
  .badge {
    display: inline-block;
    background: rgba(255,255,255,0.2);
    color: white;
    font-size: 14px;
    font-weight: 700;
    padding: 6px 14px;
    border-radius: 4px;
    text-transform: uppercase;
    letter-spacing: 1.5px;
    margin-bottom: 24px;
    width: fit-content;
  }
  .title {
    color: white;
    font-size: {{fontSize}}px;
    font-weight: 800;
    line-height: 1.2;
    max-width: 90%;
  }
  .author {
    color: rgba(255,255,255,0.7);
    font-size: 16px;
    margin-top: 24px;
  }
</style>
</head>
<body>
  <div class="container">
    <div class="badge">{{series}}</div>
    <div class="title">{{title}}</div>
    <div class="author">{{author}}</div>
  </div>
</body>
</html>

The template uses {{placeholder}} tokens that the script replaces at runtime. The gradient, font size, series badge, title, and author are all injected per post. You can add decorative elements like semi-transparent circles for visual interest without complicating the layout.

Map series to color gradients

Posts in a series should share a visual identity. A simple lookup object handles this:

const SERIES_MAP = {
  'waaseyaa':          { gradient: '#667eea, #764ba2',   label: 'Waaseyaa' },
  'php-fig-standards': { gradient: '#0f9b8e, #1a5276',   label: 'PHP-FIG Standards' },
  'codified-context':  { gradient: '#f093fb, #f5576c',   label: 'Codified Context' },
  'production-linux':  { gradient: '#e65100, #bf360c',   label: 'Production Linux' },
  '_default':          { gradient: '#2c3e50, #4ca1af',   label: 'Blog' },
};

Posts without a series get the _default gradient. The label appears in the badge above the title.

Scale the font size to the title length

Long titles need smaller text to avoid overflow. Three breakpoints cover most cases:

function getFontSize(title) {
  if (title.length < 40) return 64;
  if (title.length <= 80) return 48;
  return 36;
}

Short punchy titles get 64px. Medium titles drop to 48px. Anything over 80 characters gets 36px, which still reads well at the 1200px card width.

Walk the content directory for post metadata

The script needs each post's slug, title, and series. Walk the content directory and parse frontmatter with gray-matter:

const matter = require('gray-matter');

function findPosts() {
  const postsDir = path.join(__dirname, '..', 'content', 'posts');
  const posts = [];

  function walk(dir) {
    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
      const full = path.join(dir, entry.name);
      if (entry.isDirectory()) {
        walk(full);
      } else if (entry.name === 'index.md') {
        const raw = fs.readFileSync(full, 'utf-8');
        const { data } = matter(raw);
        if (data.slug && data.title) {
          const cleanSlug = data.slug.replace(/[\u2018\u2019\u201C\u201D]/g, '');
          posts.push({
            slug: cleanSlug,
            title: data.title,
            series: data.series || [],
          });
        }
      }
    }
  }

  walk(postsDir);
  return posts;
}

The replace on line 12 strips curly quotes from slugs. YAML parsers sometimes convert straight quotes to smart quotes, and those characters in a filename cause the image to silently not match the post.

Screenshot each post with Playwright

Launch a headless browser, set the viewport to 1200x630, inject each post's values into the template, and screenshot:

const { chromium } = require('playwright');

const browser = await chromium.launch();
const page = await browser.newPage();
await page.setViewportSize({ width: 1200, height: 630 });

for (const post of posts) {
  const info = getSeriesInfo(post.series);
  const fontSize = getFontSize(post.title);

  const html = template
    .replace(/\{\{gradient\}\}/g, info.gradient)
    .replace(/\{\{series\}\}/g, info.label)
    .replace(/\{\{title\}\}/g, post.title.replace(/&/g, '&amp;').replace(/</g, '&lt;'))
    .replace(/\{\{fontSize\}\}/g, String(fontSize))
    .replace(/\{\{author\}\}/g, 'Russell Jones');

  await page.setContent(html, { waitUntil: 'load' });
  await page.screenshot({ path: `static/images/og/${post.slug}.png`, type: 'png' });
}

await browser.close();

The setContent + screenshot pattern avoids the overhead of navigating to a URL. Playwright renders the HTML string directly. Each image takes under 100ms, so even a blog with 100+ posts finishes in seconds.

Note the HTML escaping on the title: & and < would break the template markup if injected raw.

Cache images with a template hash

Regenerating every image on every run wastes time. Hash the template file and compare against the last run:

const crypto = require('crypto');

const templateHash = crypto.createHash('sha256').update(template).digest('hex');
const HASH_FILE = path.join(OUTPUT_DIR, '.og-template-hash');

let regenerateAll = force;
if (!force && fs.existsSync(HASH_FILE)) {
  const oldHash = fs.readFileSync(HASH_FILE, 'utf-8').trim();
  if (oldHash !== templateHash) {
    console.log('Template changed — regenerating all images');
    regenerateAll = true;
  }
}

const toGenerate = regenerateAll
  ? posts
  : posts.filter(p => !fs.existsSync(path.join(OUTPUT_DIR, `${p.slug}.png`)));

// After generation:
fs.writeFileSync(HASH_FILE, templateHash);

If the template hasn't changed, only posts without an existing image get generated. Change the template and every image rebuilds. A --force flag overrides the cache for manual regeneration.

Wire it into your build

Add a task that runs the script before your static site build:

# Taskfile.yml
tasks:
  og:generate:
    desc: Generate OG images for all posts
    cmds:
      - node scripts/generate-og-images.js

  og:force:
    desc: Force-regenerate all OG images
    cmds:
      - node scripts/generate-og-images.js --force

Hugo auto-detects OG images by convention when they're at static/images/og/{slug}.png. Your hugo.toml or theme template just needs to reference that path in the og:image meta tag.

What the generated images look like

Here are three examples from this blog showing different series gradients and font sizes in action.

A standalone post gets the default slate-to-cyan gradient:

A post in the Codified Context series gets the pink gradient with the series badge:

And a PHP-FIG Standards post gets the teal-to-blue gradient:

Every image is 1200x630, uses the same layout, and the font size scales automatically based on title length. The series badge and gradient are the only things that change between posts in a series, which gives each series a consistent visual identity on social feeds.

You can see the full implementation in the blog repo: generate-og-images.js and og-template.html.

Baamaapii

Build a Hugo-to-Dev.to sync engine in Go

Russell Jones — Sun, 29 Mar 2026 19:33:58 +0000

Ahnii!

Publishing on your own blog and cross-posting to Dev.to means maintaining two copies of every article. This post covers how to build a sync engine in Go that pushes Hugo posts to Dev.to via the Forem API, keeps canonical URLs pointed at your blog, and handles the API quirks that the documentation doesn't warn you about. The full source is in tools/devto-sync/.

Prerequisites

Go 1.21+
A Dev.to API key (Settings > Extensions > Generate API Key)
A Hugo blog with posts using page bundles (content/posts/category/slug/index.md)

How frontmatter drives sync behavior

The sync engine reads Hugo frontmatter to decide what to do with each post. Three fields control everything:

---
title: "My Post"
draft: false
devto: true
devto_id: 12345
---

Field	Default	Effect
`devto`	`true`	Set to `false` to exclude a post from sync entirely
`devto_id`	`0`	Links the local post to a Dev.to article. Zero means create, nonzero means update
`draft`	`false`	Maps directly to Dev.to's published state: `draft: true` unpublishes the article

The eligibility check is straightforward:

func (p *Post) ShouldSync() bool {
    return p.DevtoEnabled() && !p.Archived
}

func (p *Post) DevtoEnabled() bool {
    if p.Devto == nil {
        return true
    }
    return *p.Devto
}

Posts opt in by default. Setting devto: false or archived: true excludes them. This means your existing posts start syncing the moment you run the tool, so add devto: false to anything you want to keep off Dev.to. (source: content.go)

The push flow: create, update, or deduplicate

The core of the engine is a single PushPost method that handles all three cases:

func (e *Engine) PushPost(post *hugo.Post, dryRun bool) (*devto.Article, error) {
    canonicalURL := fmt.Sprintf("%s/%s/", e.baseURL, post.Slug)

    req := devto.ArticleCreate{
        Article: devto.ArticleBody{
            Title:        post.Title,
            BodyMarkdown: body,
            Published:    !post.Draft,
            Tags:         sanitizeTags(post.Tags),
            CanonicalURL: canonicalURL,
        },
    }

    // Has a devto_id? Update.
    if post.DevtoID > 0 {
        return e.client.UpdateArticle(post.DevtoID, req)
    }

    // No devto_id, but an article with this canonical URL already exists?
    // Update it instead of creating a duplicate.
    existing, _ := e.client.FindByCanonicalURL(canonicalURL)
    if existing != nil {
        return e.client.UpdateArticle(existing.ID, req)
    }

    // No match anywhere. Create.
    return e.client.CreateArticle(req)
}

The canonical URL check prevents duplicates. If a previous push created an article but the devto_id writeback PR hasn't merged yet, the next push finds the existing article by its canonical URL and updates it instead of creating a second copy. (source: engine.go)

Tag sanitization: hyphens and the 4-tag limit

Dev.to silently rejects tags containing hyphens. The tag php-fig fails with no useful error. Strip them before sending:

tags := make([]string, 0, len(post.Tags))
for _, t := range post.Tags {
    sanitized := strings.ReplaceAll(t, "-", "")
    if sanitized != "" {
        tags = append(tags, sanitized)
    }
}
if len(tags) > 4 {
    tags = tags[:4]
}

php-fig becomes phpfig, and any post with more than four tags gets truncated. Dev.to enforces the four-tag limit server-side, but trimming locally gives you control over which four survive.

The FlexTags problem: one field, two formats

The Forem API returns the tag_list field as an array of strings on list endpoints (GET /api/articles/me/all) but as a comma-separated string on create/update responses. Unmarshalling into []string works for one and breaks on the other.

A custom JSON unmarshaler handles both:

type FlexTags []string

func (ft *FlexTags) UnmarshalJSON(data []byte) error {
    var arr []string
    if err := json.Unmarshal(data, &arr); err == nil {
        *ft = arr
        return nil
    }
    var s string
    if err := json.Unmarshal(data, &s); err != nil {
        return err
    }
    if s == "" {
        *ft = nil
        return nil
    }
    *ft = strings.Split(s, ", ")
    return nil
}

Try the array first. If that fails, split the string on ", " (comma-space, not just comma). This handles every response the API throws at you without branching in the calling code. (source: types.go)

Rate limiting: the real numbers

The Forem API docs say 10 requests per 30 seconds. In practice, creates are throttled harder. Three creates per 30 seconds is the safe ceiling. Separate read and write budgets with a token bucket:

type rateLimiter struct {
    max      int
    tokens   int
    interval time.Duration
    last     time.Time
}

func (r *rateLimiter) wait() {
    elapsed := time.Since(r.last)
    if elapsed >= r.interval {
        r.tokens = r.max
        r.last = time.Now()
    }
    if r.tokens <= 0 {
        time.Sleep(r.interval - elapsed)
        r.tokens = r.max
        r.last = time.Now()
    }
    r.tokens--
}

The client uses two limiters: one for creates (3/30s) and one for reads (10/30s). On a 429 response, the client reads the Retry-After header and sleeps before retrying once. (source: client.go)

Dev.to also has a separate "title already used in the last 5 minutes" rate limit that fires if you create, delete, and recreate an article with the same title. There is no workaround except waiting.

Transforming Hugo content for Dev.to

Hugo shortcodes like {{</* relref "post-slug" */>}} mean nothing on Dev.to. The transform step converts them to full URLs:

body, warnings := hugo.TransformForDevto(post.Body, e.baseURL, postPath)

The transformer resolves relref shortcodes to absolute URLs using the blog's base URL, converts relative image paths to absolute URLs, and strips unknown shortcodes with a warning. Each warning is logged so you can fix shortcodes that don't have a Dev.to equivalent. (source: transform.go)

Finding orphan articles with match

Old RSS imports or manual cross-posts can leave articles on Dev.to that hold your canonical URL but have no devto_id in your frontmatter. The match command finds them:

bin/devto-sync match

It pulls all your Dev.to articles, then runs two passes against your local posts:

Canonical URL match: compares article.canonical_url against the expected {baseURL}/{slug}/
Title match (fallback): case-insensitive title comparison for articles without canonical URLs

Output is tab-separated for easy scripting:

CANONICAL   my-post-slug    12345   My Post Title
TITLE       other-post      67890   Other Post
NONE        new-post        0       no match found

Matched IDs can be written back to frontmatter with a force pull, linking the local post to its Dev.to counterpart without creating a duplicate. (source: match.go)

Automated sync with GitHub Actions

The sync runs automatically after every deploy:

- name: Push changed posts to Dev.to
  run: bin/devto-sync push --all
  env:
    DEVTO_API_KEY: ${{ secrets.DEVTO_API_KEY }}

After creating new articles, the tool writes devto_id back into the post frontmatter. A second workflow step opens a PR with those changes so the IDs are tracked in git. The next push uses the IDs for updates instead of creates.

This closes the loop: push to main, deploy triggers, sync runs, IDs come back as a PR. (source: devto-sync.yml)

Baamaapii