DEV Community: Russell Jones

Agent-friendly JSON output for PHP CI tools

Russell Jones — Sun, 24 May 2026 19:33:07 +0000

Ahnii!

When an AI agent runs your test suite or a CI gate during an implement-or-review loop, the verbose stdout gets piped straight back into its context window. A full PHPUnit run on the Waaseyaa framework monorepo is around 12,000 lines. bin/check-package-layers is about 600. Per iteration, per gate. The token cost is real, and it compounds across review cycles. This post walks through waaseyaa/agent-output, a Layer 0 package that shrinks that output to a single NDJSON line for agents while leaving human terminal output completely unchanged.

Why agent context windows hate CI output

The pattern shows up the moment you let an agent drive your test loop. The agent runs composer test. PHPUnit emits its banner, then a dot per test, then a footer summary, then optionally a slow-test report. None of that helps the agent. It needs three things: did the run pass, what failed, where. Everything else is noise that displaces real signal.

The same is true for bin/check-package-layers, bin/check-phpstan, tools/drift-detector.sh, and friends. Each one is a CI gate that the agent already understands at the contract level. The full human-readable output exists to help a person scan and react. An agent does not need any of it.

What the package does

waaseyaa/agent-output is a single-purpose Layer 0 package (no waaseyaa/* runtime deps, installable standalone). It does three things:

Detects an agent runtime from a list of well-known env vars (CLAUDE_CODE, CURSOR_AGENT, and the rest), extensible.
Provides a FormatterInterface and first-party formatters for PHPUnit, Pest, PHPStan, the bin/check-* CI gates, and the drift detector.
Honors three activation triggers per command: an --output=json flag, a WAASEYAA_OUTPUT=json env var, or auto-activation when an agent env var is set.

When none of those triggers apply, the affected command emits exactly the human output it always did. No JSON fields leak, no exit codes change.

Three ways to flip a tool into agent mode

bin/check-package-layers --output=json
WAASEYAA_OUTPUT=json bin/check-package-layers
CLAUDE_CODE=1 bin/check-package-layers

The first is explicit per-invocation. The second sets it for the shell. The third is what happens automatically when Claude Code (or another supported agent) drives your terminal — you do not have to wire anything up; the auto-detection kicks in.

Coverage

Here is the full set of tools the package now covers, taken verbatim from the package README:

Tool	Trigger	Formatter
`bin/check-package-layers`	`--output=json` / env	`PackageLayersFormatter`
`bin/check-dead-code`	`--output=json` / env	`DeadCodeFormatter`
`bin/check-getquery-bindings`	`--output=json` / env	`GetQueryBindingsFormatter`
`bin/check-composer-policy`	`--output=json` / env	`ComposerPolicyFormatter`
`bin/check-phpstan`	`--output=json` / env	`PhpStanFormatter`
`tools/drift-detector.sh`	`--output=json` / env	`DriftDetectorFormatter`
`vendor/bin/phpunit`	`WAASEYAA_OUTPUT=json` (PHPUnit does not surface custom CLI flags)	`PhpUnitFormatter` via `AgentOutputPhpUnitExtension`

Five bin/check-* scripts, a drift detector, and PHPUnit. Each one emits an NDJSON envelope through a formatter dedicated to that tool's domain.

PHPUnit is the awkward one

PHPUnit's extension API does not surface custom CLI flags. There is no clean way to add --output=json and have PHPUnit pass it to your extension. So the env var is the canonical trigger, and the package ships a PHPUnit 10 extension that registers six event subscribers (passed, failed, errored, marked-incomplete, skipped, execution-finished) over a shared run-state object:

final class PhpUnitRunState
{
    public int $passed = 0;
    public int $failed = 0;
    public int $skipped = 0;

    /** @var list<array{test: string, file: string, line: int, message: string}> */
    public array $failures = [];
}

That class lives in its own file rather than as an anonymous shape inside the extension, so PHPStan can type-check the field accesses without inferring mixed through anonymous classes. A small thing, but it is the kind of detail that decides whether a package's own lint suite stays green.

The extension itself is a no-op when WAASEYAA_OUTPUT is not json — zero overhead in human mode. When it is, the envelope is printed at TestRunner\ExecutionFinished with a leading newline so it lands on its own trailing line. Agent consumers read the file line-by-line and parse the line that starts with {"tool":"phpunit".

What the numbers say

WP06 of the mission was an empirical token-reduction smoke test against the original NFR. The headline result, measured on packages/foundation/tests/Unit --no-coverage:

Standard PHPUnit output: 2,209 bytes
Agent envelope (NDJSON line only): 117 bytes
Reduction: 94.70%

The threshold was ≥90%. The pattern delivers. And that number understates the savings on a full monorepo run, where the human output runs in the thousands of lines and the envelope stays a single line.

Why not just use Laravel PAO?

The pattern was lifted from Laravel PAO (released around May 2026), but the package is framework-native for two reasons. First, PAO does not cover the custom CI gates the Waaseyaa monorepo runs as hard gates (bin/check-package-layers and the rest). Second, the formatters need to live alongside the gate scripts so the contract between script and envelope shape can evolve in the same PR — third-party packaging would have made that coupling awkward.

The package is also a Layer 0 dependency, which means anyone outside the Waaseyaa monorepo can install just waaseyaa/agent-output and reuse the formatter interface for their own tools. The detection logic and envelope contract travel; the bin/check-* wrappers stay in the framework where they belong.

Try it in your own monorepo

composer require waaseyaa/agent-output

Then either pass --output=json to any supported script, set WAASEYAA_OUTPUT=json in your shell, or run under an agent that sets CLAUDE_CODE=1. For PHPUnit specifically, register the extension in phpunit.xml.dist:

<extensions>
    <bootstrap class="Waaseyaa\AgentOutput\Listener\AgentOutputPhpUnitExtension"/>
</extensions>

The extension self-disables when WAASEYAA_OUTPUT is not set to json, so registering it does not change human-mode output.

For the full envelope schema, formatter contract, and a guide for writing third-party formatters, see docs/specs/agent-output.md in the framework repo.

Baamaapii

Spot the AI: can you tell which passage Claude wrote?

Russell Jones — Sat, 23 May 2026 21:11:45 +0000

Ahnii!

Spot the AI is a small web game. You're shown two short passages, one written by a human author and one written by Claude, and you pick which one is the AI. This post is a heads up that the game is live and an invitation to play a few rounds.

How to play

Open spot-the-ai.oiatc.ca.
Read both passages.
Pick the one you think Claude wrote.

That is the whole loop. No account, no setup.

Why it exists

People talk a lot about AI writing without testing whether they can actually tell the difference. The game is a tiny way to test yourself before you make claims about what AI writing sounds like.

It is also a small thing under the OIATC umbrella, which is the broader push toward Indigenous-controlled AI tooling and infrastructure. Most of that work happens out of view. This one happens to be playable in a browser.

Play a few rounds and see how you do.

Baamaapii

Bumping a PHP monorepo to 8.5: the mechanics

Russell Jones — Mon, 11 May 2026 18:22:30 +0000

Ahnii!

This is the first of three posts about taking Waaseyaa to PHP 8.5. This one is about the mechanics: how a coordinated version bump across a 67-package monorepo actually happens. The next two cover the deprecation sweep that came with it and the features we deliberately did not adopt.

Context: Waaseyaa is the open-source PHP framework I have been writing about. Mission: php-8-5-upgrade-01KR8DN2. Shipped as PR #1406, merge commit e0f8cb57. Released in alpha.176.

The starting state

Before the bump, Waaseyaa required PHP 8.4. Sixty-six first-party composer.json files, all aligned on >=8.4. Plus a skeleton package, which is a template artifact and is kept at the lowest reasonable floor on purpose.

CI ran a single PHP version. PHPStan was pinned to a matching phpVersion. The floor was tight and consistent. That alignment is what makes a bump cheap. The expensive version of this story is the one where every package picks its own minimum and you have to negotiate sixty-six exceptions.

Mission shape

The mission split into five work packages plus a closing one:

WP01. Constraint bump, CI, Docker, lockfile, PHPStan pin, docs, governance charter touch.
WP02. 8.5 deprecation sweep.
WP03. Adopt #[\NoDiscard] on critical surfaces.
WP04. Targeted array_find() adoption.
WP05. PHP-CS-Fixer migration rules.
WP06. CHANGELOG and verification.

WP01 is the only one that touches the floor. Everything after is feature work that becomes available because the floor moved. Splitting it this way matters: if WP01 lands clean, the rest can land in any order without coupling.

What WP01 actually changed

The mechanical surface of a floor bump is smaller than people expect. From the merge:

66 first-party composer.json files updated from >=8.4 to >=8.5.
3 GitHub Actions workflows repinned to php-version: '8.5': ci.yml, skeleton-smoke.yml, release-cut.yml. Ten total occurrences of the string '8.5'.
phpstan.neon updated: phpVersion: 80500.
Lockfile regenerated against 8.5.

That is the bump. Everything else in the mission is downstream of those four artifacts moving in lockstep.

The reason the surface is small is that Waaseyaa has hard gates that already enforce alignment. There is a bin/check-composer-policy script that fails CI if any package drifts from the root constraint. There is a bin/check-package-layers script that fails if the dependency direction inverts. There is a tools/drift-detector.sh that fails if docs lag the code. The floor is one number defended in many places.

The verification surface

For a bump to be safe, every hard gate has to be green on the new floor. Waaseyaa's full gate list for this mission:

composer phpstan (root level + package level)
vendor/bin/phpunit
composer cs-check
bin/check-composer-policy
bin/check-package-layers
bin/audit-dead-code
tools/drift-detector.sh

At merge time the test suite was 7,497 unit tests, 18,118 assertions, 0 deprecations, 2 expected skips. That is the number to trust. Not because tests prove a version is fine, but because the test corpus is dense enough that deprecation warnings would surface.

Why split it into work packages at all

This is the part worth paying attention to if you maintain a PHP monorepo. The actual diff for a version bump is small. You could do it in one PR with one commit. People do.

The cost of doing it that way is that the diff conflates four different kinds of change:

The floor moves (a policy change).
Deprecations get removed (a behavior change).
New features get adopted (a style change).
New tooling gets wired (a configuration change).

When all four land in one squash commit, the next person to touch any of them cannot read the rationale. Six months later, someone reverts a #[\NoDiscard] attribute thinking it is part of the floor bump, and now the floor bump cannot be reverted cleanly either.

The work package structure makes each kind of change auditable on its own terms. WP02 is removable without affecting WP01. WP04 can be reverted without touching WP03. The mission directory is the persistent record of why each was done.

That is the same point I made about the Spec Kitty mission lifecycle post: the output of any mission is replaceable. The trail is not.

What the next posts cover

Post 2 in this series digs into the deprecation sweep: what 8.5 surfaced, where it was hiding in the codebase, and how the sweep got from 34 warnings to 0.

Post 3 covers the features we deliberately did not adopt. Property hooks. The pipe operator. Broader array_find(). The argument is that restraint is part of the upgrade, not absent from it.

Baamaapii

PHP 8.5 restraint: features we did not adopt

Russell Jones — Mon, 11 May 2026 18:21:56 +0000

Ahnii!

Third in the PHP 8.5 upgrade series. Post one was the floor-bump mechanics. Post two was the deprecation sweep. This one is about what we deliberately did not adopt.

Most upgrade write-ups read like a feature tour. Here is what is new, here is how to use it. They are useful and they are not the whole story. The other half of an upgrade is what you choose not to add. That choice is invisible in the diff and load-bearing in the codebase.

Mission: php-8-5-upgrade-01KR8DN2, merge commit e0f8cb57. Five work packages shipped. Property hooks were not in any of them.

Property hooks: not in scope

PHP 8.4 introduced property hooks. Define get and set on a property directly, eliminate the boilerplate getter and setter pair. Asymmetric visibility came in the same window. Lots of writeups called this the biggest PHP language change in years.

Waaseyaa did not adopt either. The mission spec did not mention them. The plan did not list them as a non-goal. They simply were not part of the upgrade.

If you grep the codebase for the patterns property hooks would replace, you will find traditional methods everywhere:

public function getClientId(): string
{
    return $this->clientId;
}

public function setClientId(string $clientId): void
{
    $this->clientId = $clientId;
}

Boring. Repetitive. Could be a property hook. Was not converted.

The reason this is intentional rather than accidental: the mission was scoped to "raise the PHP requirement and fix what 8.5 surfaces, plus a focused 8.5 feature-adoption pass." Property hooks are an 8.4 feature, not an 8.5 feature. The line was drawn at the version being adopted.

That line is the discipline. An upgrade pass is a window where adopting new patterns is cheap because everyone is reading the diff anyway. The temptation is to use the window for everything. The cost of using it for everything is that the diff conflates "we now require 8.5" with "we changed our property style." Two reverts deep, those become impossible to separate.

Property hooks are not rejected. They are deferred. They get their own mission when the conversion is the work, not a side effect of something else.

The pipe operator: not used

PHP 8.5 introduced |>, a pipe operator that lets you write $x |> $fn1 |> $fn2 instead of nested calls.

Waaseyaa shipped 8.5 without using |> anywhere. The plan considered it in WP04 alongside array_first() and array_find(). After the survey pass, no use sites were strong enough to take.

The reason is that pipe shines when you have a multi-step transform that reads naturally as a chain. Waaseyaa's transforms are usually one-step (use a function), two-step (assign an intermediate), or many-step but heterogeneous (a builder pattern with named methods). The middle band where pipe wins is narrow.

Adopting |> at every two-step site for style would create a second idiom alongside the existing intermediate-variable style. Mixed idioms have a tax: every reader has to decide which style is in play before reading. That tax is paid every time the file is opened.

So pipe stays unused until a real call site asks for it. Then it gets adopted in that one place. Not across the codebase.

`array_find()`: two adoptions, five rejections

The most interesting case. PHP 8.5 added array_find() for "first matching element or null." The surface use case is exactly the foreach-and-return-first pattern that shows up in every codebase.

WP04 surveyed seven candidate sites. Two were adopted. Five were rejected.

The two adoptions

packages/search/src/SearchResult.php::getFacet():

// Before
foreach ($this->facets as $facet) {
    if ($facet->name === $name) {
        return $facet;
    }
}
return null;

// After
return array_find(
    $this->facets,
    static fn(SearchFacet $facet): bool => $facet->name === $name,
);

packages/cli/src/Testing/CliTester.php::findOption() follows the same pattern. Three lines of foreach become one array_find() with a typed predicate.

Both sites win because the return type is ?SearchFacet or ?OptionDefinition. The null case is a real outcome the caller handles. array_find returns null when nothing matches, and that lines up cleanly with the existing contract.

The five rejections

SqlEntityStorage, AuthController, EntityResolver, JsonApiController, DbalTransport. The mission notes give one rationale that covers all five:

all rejected because the surrounding type contracts (load() accepts int|string, not null) require an explicit empty guard either way

The point is subtle. array_find() returning null is only a win if the caller wants null. If the caller's contract guarantees non-null (because the input was validated upstream, or because nullness is an error condition), then the foreach version is doing two things: searching and asserting. Replacing it with array_find() keeps the search but loses the assertion. You end up writing an explicit guard right after the array_find() call. The line count is the same. The intent is worse.

The fastest way to spot this in your own codebase: read the immediate caller of the candidate site. If it does throw or assert on the result, do not adopt array_find() there. The foreach is encoding more than iteration.

What was adopted, intentionally

To be specific about what restraint does not mean: WP03 added #[\NoDiscard] to sixteen API surfaces. Four allowed/forbidden/neutral factory methods on AccessResult. Five repository interface methods that return loaded entities. Ten fluent-builder methods on DBALSelect that return the modified builder.

#[\NoDiscard] is a semantic safety net. If a caller ignores a find() return value they probably have a bug. The attribute makes the compiler say so. Adopting it on sixteen surfaces was a security-shaped decision, not a style one.

WP05 also wired three mechanical PHP-CS-Fixer rules: octal_notation (52 sites converted to 0o755), new_expression_parentheses (58 chained-new conversions), and heredoc_indentation (8 SQL and HTML heredocs reindented). Mechanical, fixer-driven, no judgement required per site. Easy to adopt at scale because the fixer makes the decision.

The pattern across both: adoption is at its best when it is either a safety improvement on a critical surface, or a mechanical fixer rule that can be applied uniformly. Adoption is at its worst when it is a style change applied site by site by humans.

The point

An upgrade is a decision about what to add and what not to add. Both decisions live in the diff. The "did not adopt" decisions are invisible if you only read the merged code, which is why they are worth writing down somewhere.

Mission directories are the place we write them down. The five-site rejection rationale for array_find() is one line in WP04's notes. Six months from now, someone will look at SqlEntityStorage::load() and think "why isn't this array_find()?" The mission directory has the answer.

If your team is doing a PHP 8.5 upgrade, the most useful thing you can write down is not the list of features you adopted. It is the list of features you considered and rejected, with one sentence each. That list is what makes the upgrade a position, not a checklist.

Baamaapii

The PHP 8.5 deprecation sweep: from 34 warnings to zero

Russell Jones — Mon, 11 May 2026 18:21:52 +0000

Ahnii!

Second in the PHP 8.5 upgrade series. The first post covered the floor-bump mechanics. This one is about what 8.5 surfaced when the floor moved and how the sweep cleared it.

Mission: php-8-5-upgrade-01KR8DN2, work package WP02. Merge commit e0f8cb57. The CHANGELOG entry for alpha.176 records the verification: 34 PHPUnit deprecations to 0, across 7,497 tests.

The starting number

Before WP02 ran, the test suite was emitting 34 deprecation warnings against 8.5. That number does not measure how broken the codebase was. It measures how dense the test corpus is. A weaker test suite would have surfaced fewer warnings because fewer code paths run during CI.

PHPUnit's deprecation handling matters here. Waaseyaa runs PHPUnit in strict mode where deprecation messages are captured and counted per test, not just printed. The mission's exit criterion was zero deprecations on the matrix that already ran 18,118 assertions.

Three categories, twenty-nine sites

The 34 warnings collapsed into three deprecation patterns once you grouped them. Twenty-nine distinct call sites across the monorepo.

1. `Reflection*::setAccessible()` — 22 sites

The biggest category. ReflectionMethod::setAccessible() and ReflectionProperty::setAccessible() were marked as no-ops in PHP 8.1 (private members became reflectively accessible by default) and deprecated outright in 8.5.

Twenty-two call sites across seven test files. Packages: entity, user, ssr, foundation, entity-storage, and one integration test under tests/Integration/Phase13/.

Every site looked roughly like this:

$reflection = new ReflectionMethod($object, 'privateMethod');
$reflection->setAccessible(true);
$reflection->invoke($object, $arg);

The fix was deletion. The line that called setAccessible(true) was removed. The line that called invoke() worked unchanged. No behavior change at runtime. The reflection access was already implicit.

This is the cleanest kind of deprecation removal you can do: the warning was telling you the line was already useless.

2. `$http_response_header` — 1 site

A single site in packages/http-client/src/StreamHttpClient.php. The magic global variable $http_response_header was deprecated in favor of the explicit function http_get_last_response_headers().

Before:

$headers = $http_response_header ?? [];

After:

$headers = http_get_last_response_headers() ?? [];

Same null-coalesce default. Explicit function call instead of a side-effect global. Easier to read, easier to mock, easier to grep for.

This is the kind of language cleanup that arrives one site at a time when the language standardizes a long-running pattern. PHP's magic globals are slowly being retired across the major versions.

3. `curl_close()` — 6 sites

Six call sites of curl_close(), deprecated in 8.5 because libcurl has treated it as a no-op since version 7.20.0. PHP held onto the function for years for compatibility. 8.5 finally removes it.

Files:

packages/ai-agent/src/Provider/AnthropicProvider.php — 3 sites
packages/ai-agent/src/Provider/OpenAiCompatibleProvider.php — 2 sites
packages/mercure/src/MercurePublisher.php — 1 site

All six were paired with curl_exec() calls in HTTP request flows. Removed without replacement. The cURL handle is collected by GC when it goes out of scope.

A second tautological PHPStan warning was cleaned up in the same area while we were there. Worth noting because deprecation sweeps are a good moment to fix the things you keep walking past.

What did not get removed

WP02 was a deprecation sweep, not a code cleanup. The bar for removal was "PHP 8.5 marks it deprecated" or "PHPStan reports it tautological in the file we are already editing." Nothing else.

That bar matters. It is tempting during an upgrade to fold in unrelated cleanup. The reason not to is that the diff stops being readable. A reviewer looking at WP02 should be able to read it as "deprecation removals" with no surprises. Adding "and we also renamed this variable while we were there" makes every line of the diff a question.

The verification

The exit criterion was numeric and binary. Run the full suite. Count deprecations. The number must be zero.

Locked by full PHPUnit (7497 tests / 18118 assertions / 0 deprecations / 2 expected skips)

That line in the CHANGELOG is the work package's signature. Two expected skips are environment-dependent tests that always skip in CI (Redis, Mercure broker variants). Zero deprecations across 7,497 tests is dense enough coverage that a future deprecation drift would surface immediately.

If you are running a similar sweep on your own codebase, the methodology is straightforward:

Move the PHP floor.
Run the full test suite. Capture deprecation output.
Group warnings by the deprecation key (E_USER_DEPRECATED message, function name, or class).
For each group, write a one-line removal pattern and apply it across all sites in one commit per group.
Rerun. The number is zero or it is not done.

The reason to group by deprecation pattern (not by file) is that each group has the same fix. Mixing them in one commit makes the diff hard to read and impossible to revert selectively.

Post 3 in the series covers the features 8.5 introduced that we deliberately did not adopt. Property hooks. The pipe operator. Broader array_find() adoption beyond the two confirmed sites. The reasoning is that restraint is part of the upgrade, not the absence of one.

Baamaapii

Spec Kitty mission lifecycle: a domain modeling pass through Giiken

Russell Jones — Mon, 11 May 2026 16:24:24 +0000

Ahnii!

A lot of agent frameworks promise "end to end" workflows. Most of them stop at "generate a plan and hope." Spec Kitty is different. It runs a real mission through a state machine, with artifacts on disk and gates between phases. This post walks one of those missions, giiken-domain-modeling-01KR2HKT, from spec to merge.

Context: Giiken is the community knowledge service built on Waaseyaa. The mission did discovery and docs for its domain model. Real commit: waaseyaa/giiken@5b2328b.

What "a mission" actually is

A Spec Kitty mission is a directory under kitty-specs/, named with a slug and an ULID. After this mission landed, that directory looked like this:

kitty-specs/giiken-domain-modeling-01KR2HKT/
  spec.md
  plan.md
  research.md
  data-model.md
  meta.json
  status.json
  status.events.jsonl
  mission-events.jsonl
  checklists/
    requirements.md
  research/
    evidence-log.csv
    source-register.csv

That is not a generated artifact dump. Each file has a role in the state machine. spec.md is the contract. plan.md is the chosen approach. research.md plus the CSVs are the evidence trail. status.json and the two .jsonl files are the lane state and the audit log. The checklist is a hard gate, not a suggestion.

The phases

The mission moved through these phases. Each one writes an artifact and emits a status event.

Specify. Compile a spec.md from the mission brief. Requirements get checklisted. Ambiguity gets surfaced before code touches the repo.
Plan. Choose an approach in plan.md. Inputs from spec. Output is the shape of the work.
Tasks. Break the plan into work packages (WPs). Each WP is independent enough to assign and review on its own.
Implement. Each WP runs through implement and review until approved. State transitions go through the orchestrator, not by hand.
Review. Per WP, against the spec. Reviewers can reject with structured feedback.
Merge. Once every WP is approved, the mission squash-merges and the events log records the terminal state.

The thing that makes this different from a long prompt is that every transition is gated. You can't move a WP to approved without a passing review. You can't merge with WPs still in flight. The agent is constrained to the shape of the state machine.

What this mission actually produced

Beyond the kitty-specs directory, the merge commit added two architecture documents to the Giiken repo:

docs/architecture/domain-model.md
docs/architecture/lifecycle.md

And the implementation work in WP01 and WP02 left the data model migration-aligned, with PHPUnit and Vitest both green at merge time. Thirteen files in one squash commit, all traceable back to the spec.

The point is the trail. A reader six months from now can open kitty-specs/giiken-domain-modeling-01KR2HKT/ and see: what was asked for, what was chosen, what evidence informed it, what got built, and which checks passed. That is a working memory you can hand to the next agent or the next human.

Why this matters more than the output

The output of this mission is fine. Useful, even. But the output is replaceable. The trail is not.

If you have been around agent workflows for any length of time, you know the failure mode: an AI session ends, the context evaporates, and the next session has to reconstruct everything from the code. Spec Kitty inverts that. The mission directory is the persistent context. The next agent picks up the spec and the checklist, not a chat log.

That is the lifecycle proof: not "an agent shipped code," but "an agent moved through a structured workflow that another agent or human can audit, resume, or extend."

Try it

If you want to see one of these missions in your own repo, the easiest path is to install Spec Kitty and run spec-kitty next --agent <name> on a small scope. Pick something with a clear question, not a vague refactor. Discovery missions like this one are a good first try.

The commit for the mission described here is waaseyaa/giiken@5b2328b. The full mission directory is in that repo at kitty-specs/giiken-domain-modeling-01KR2HKT/.

Baamaapii

Hugo blog shortcodes: adding a visual component system to PaperMod

Russell Jones — Wed, 08 Apr 2026 20:41:09 +0000

Ahnii!

PaperMod is a clean, fast Hugo theme. What it doesn't give you out of the box is a component library: no callouts, no numbered steps, no before/after comparisons. If you write tutorials or technical posts, you end up compensating with blockquotes and bold text where purpose-built components would serve the reader better.

This post covers all six shortcodes, the CSS behind them, and how to add the same components to your own PaperMod blog. All of it came together in a single Claude Code session.

What we're building

Six shortcodes, one CSS file:

callout: highlighted aside with five severity types
steps / step: auto-numbered procedure blocks
pullquote: large-format quote for emphasis
stats / stat: side-by-side metric tiles
compare / before / after: side-by-side comparison panels
cta: call-to-action box with a button

All styles hook into PaperMod's CSS variables (--primary, --entry, --border, etc.), so they adapt to dark and light mode automatically.

File locations

Hugo resolves shortcodes from layouts/shortcodes/. Create one .html file per shortcode:

layouts/shortcodes/
  callout.html
  steps.html
  step.html
  pullquote.html
  stats.html
  stat.html
  compare.html
  before.html
  after.html

The CSS goes in assets/css/extended/. PaperMod loads everything in that directory automatically; no import statements needed.

The shortcodes

Callout

A callout is a highlighted aside that draws the reader's attention. It accepts a type parameter: info, warning, tip, note, or success. Defaults to note.

Template (layouts/shortcodes/callout.html):

{{- $type := .Get "type" | default "note" -}}
{{- $emoji := dict "info" "💡" "warning" "⚠️" "tip" "✨" "note" "📝" "success" "✅" -}}
<div class="callout callout-{{ $type }}">
  <div class="callout-marker">{{ index $emoji $type }}</div>
  <div class="callout-body">{{ .Inner | markdownify }}</div>
</div>

Usage:

{{</* callout type="warning" */>}}
Run `git stash` before switching branches or you will lose your changes.
{{</* /callout */>}}

Rendered:

Run git stash before switching branches or you will lose your changes.

The markdownify call means you can use inline markdown inside the body: backtick code, bold, links. All render correctly.

Steps and step

The steps shortcode wraps a sequence of step shortcodes. Each step takes a title as its first positional argument and auto-numbers itself via CSS counters. No JavaScript, no manual numbering.

Templates (layouts/shortcodes/steps.html and step.html):

<!-- steps.html -->
<div class="steps">{{ .Inner }}</div>

<!-- step.html -->
<div class="step">
  <div class="step-badge"></div>
  <div class="step-body">
    <div class="step-title">{{ .Get 0 }}</div>
    <div class="step-content">{{ .Inner | markdownify }}</div>
  </div>
</div>

Usage:

{{</* steps */>}}
{{</* step "Create the shortcode file" */>}}
Add `layouts/shortcodes/callout.html` to your project.
{{</* /step */>}}
{{</* step "Add the CSS" */>}}
Create `assets/css/extended/components.css` with the component styles.
{{</* /step */>}}
{{</* /steps */>}}

Rendered:

Add layouts/shortcodes/callout.html to your project.

Create assets/css/extended/components.css with the component styles.

Stats and stat

The stats shortcode is a flex container for stat tiles. Each stat takes two positional arguments: the value and the label.

Templates (layouts/shortcodes/stats.html and stat.html):

<!-- stats.html -->
<div class="stats">{{ .Inner }}</div>

<!-- stat.html -->
<div class="stat">
  <div class="stat-number">{{ .Get 0 }}</div>
  <div class="stat-label">{{ .Get 1 }}</div>
</div>

Usage:

{{</* stats */>}}
{{</* stat "6" "shortcodes" */>}}
{{</* stat "1" "CSS file" */>}}
{{</* stat "0" "JS required" */>}}
{{</* /stats */>}}

Rendered:

The tiles flex-wrap on small screens, so they stack gracefully on mobile without extra media query work.

Compare, before, and after

Three files work together: compare.html wraps the pair, before.html and after.html render each panel. The before panel uses PaperMod's warning colour; after uses the success colour.

Templates (compare.html, before.html, after.html):

<!-- compare.html -->
<div class="compare">{{ .Inner }}</div>

<!-- before.html -->
<div class="compare-before">
  <div class="compare-marker">✕</div>
  <div class="compare-body">{{ .Inner | markdownify }}</div>
</div>

<!-- after.html -->
<div class="compare-after">
  <div class="compare-marker">✓</div>
  <div class="compare-body">{{ .Inner | markdownify }}</div>
</div>

Usage:

{{</* compare */>}}
{{</* before */>}}
Blockquote hacks repurposed as callouts.
{{</* /before */>}}
{{</* after */>}}
Purpose-built `callout` shortcode with five types.
{{</* /after */>}}
{{</* /compare */>}}

Rendered:

Blockquote hacks repurposed as callouts.

Purpose-built callout shortcode with five types.

On screens narrower than 600px the panels stack vertically.

Pullquote

A pullquote is a styled blockquote for emphasis. Use it to surface a key insight or memorable line from the surrounding text.

Template (layouts/shortcodes/pullquote.html):

<blockquote class="pullquote">
  {{ .Inner | markdownify }}
</blockquote>

Usage:

{{</* pullquote */>}}
Good writing tools get out of the way. Good components make the writing better.
{{</* /pullquote */>}}

Rendered:

Good writing tools get out of the way. Good components make the writing better.

CTA

A call-to-action box with a centred button. Takes three named parameters: title, button, and href. The inner body is optional copy.

Template (layouts/shortcodes/cta.html):

{{- $title := .Get "title" -}}
{{- $button := .Get "button" -}}
{{- $href := .Get "href" -}}
<div class="cta">
  <h3 class="cta-title">{{ $title }}</h3>
  <div class="cta-body">{{ .Inner | markdownify }}</div>
  <a class="cta-button" href="{{ $href }}">{{ $button }}</a>
</div>

Usage:

{{</* cta title="Try it yourself" button="View the source" href="https://github.com/jonesrussell/blog" */>}}
All six shortcodes and the CSS are in the repo.
{{</* /cta */>}}

Rendered:

All six shortcodes and the CSS are in the repo.

The proving ground

Before calling the system done, retrofit an existing post. I used Minoo Elders, replacing a flat numbered list with a steps block and a closing paragraph with a cta. If the shortcodes work in a real post with real content, they are ready.

The retrofit caught a line-height edge case in the step badge CSS and confirmed the dark mode colours held in both themes. Worth the ten minutes.

Vibe coding the component system

This system was built with Claude Code in one session. Describe the component you want, review the draft, push back on anything over-engineered. Nine files and the CSS came together without a lot of manual effort.

The real gain is in the iteration loop: see a render, request a tweak, get updated CSS in thirty seconds. That speed is the whole point.

Baamaapii

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

DEV Community: Russell Jones

Agent-friendly JSON output for PHP CI tools

Why agent context windows hate CI output

What the package does

Three ways to flip a tool into agent mode

Coverage

PHPUnit is the awkward one

What the numbers say

Why not just use Laravel PAO?

Try it in your own monorepo

Spot the AI: can you tell which passage Claude wrote?

How to play

Why it exists

Bumping a PHP monorepo to 8.5: the mechanics

The starting state

Mission shape

What WP01 actually changed

The verification surface

Why split it into work packages at all

What the next posts cover

PHP 8.5 restraint: features we did not adopt

Property hooks: not in scope

The pipe operator: not used

array_find(): two adoptions, five rejections

The two adoptions

The five rejections

What was adopted, intentionally

The point

The PHP 8.5 deprecation sweep: from 34 warnings to zero

The starting number

Three categories, twenty-nine sites

1. Reflection*::setAccessible() — 22 sites

2. $http_response_header — 1 site

3. curl_close() — 6 sites

What did not get removed

The verification

Next post

Spec Kitty mission lifecycle: a domain modeling pass through Giiken

What "a mission" actually is

The phases

What this mission actually produced

Why this matters more than the output

Try it

Hugo blog shortcodes: adding a visual component system to PaperMod

What we're building

File locations

The shortcodes

Callout

Steps and step

Stats and stat

Compare, before, and after

Pullquote

CTA

The proving ground

Vibe coding the component system

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

Day One Output: 20 Issues, Too Much Noise

Fix 1: Tighten the Mining Filter

Fix 2: Merge-in-Curation

Fix 3: Put the Blog First

Why Content Pipelines Need Continuous Refinement

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

What a Dispatcher Does

Why a Monolithic Dispatcher Breaks Down

The DomainRouterInterface Contract

EntityTypeLifecycleRouter: A Complete Example

SchemaRouter: Same Pattern, Different Domain

Routers Get a Fully Loaded Request

Adding a New Router

What This Gets You

Remember when server-side rendering was just rendering?

What the rendering pipeline actually does

How entities become template variables

Field formatters: type-safe output without the ceremony

Template resolution: the chain loader

Template suggestions: specificity without complexity

What this isn't

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

Why a Framework Without a Playbook Doesn't Stick

Define Your AI Boundary Table

`array_find()`: two adoptions, five rejections

1. `Reflection*::setAccessible()` — 22 sites

2. `$http_response_header` — 1 site

3. `curl_close()` — 6 sites