From JBake to Hugo: a Website Migration Planned with Werkbaum

This website ran for years on a self-patched fork of JBake. The fork was convenient as long as I held it in my head, but every layout change meant: Freemarker templates, an old CSS framework with jQuery, and outdated Java code. Now the site runs on Hugo with the well-maintained theme Blowfish, two languages under /de/ and /en/, and all old URLs redirect.

This article documents how I approached the migration. The focus is on Werkbaum, my tool for project planning with work breakdown structures, and on why this kind of planning, in my experience, suits working with agentic AI particularly well. The implementation itself was done by an AI agent, in my case mostly Claude Code with Fable 5.1, plus minor follow-up corrections to my static pages with OpenCode and Muse Spark 1.3.

For this migration, I chose a simplified approach. How I generally work with agentic AI in software development is the topic of a separate, later article.

Starting Point

#

The initial inventory revealed more legacy burden than I had expected:

• 73 articles, 57 of them HTML from an even older WordPress import and 16 in AsciiDoc, plus 7 pages; 44 articles in German, 29 in English, with no translation pairs.
• 17 admonitions, 6 include:: directives with tag regions from source files, 4 callouts, two articles with MP3 recordings.
• 23 internal links to files from the WordPress era that were never in the repository, only on the webspace.
• An .htaccess with 121 redirects of old WordPress paths that had to keep working, and tag URLs with spaces, umlauts, and mixed case.

The goals were correspondingly sober: A maintained theme, only visually polished with custom CSS, instead of custom templates, real multilingualism instead of mixed lists, no external requests, every old URL with a 301 redirect, and build plus deployment via Werkator, my own CI/CD server, which also runs without Docker support in a Hostsharing managed webspace.

The Plan as a Werkbaum

#

In a chat with Claude Code, the requirements were evaluated: which static site generator to use at all, and which templates would be candidates. The first commit of the migration was therefore not code, but the plan: doc/Hugo-Migration.werkbaum, a text file in Werkbaum notation. Abridged, it looked like this at the start:

[ ] #relaunch: Website relaunch michael.hoennig.de with Hugo (XL)
  - [ ] #inventar: Inventory (S)
    - [ ] #content-inv: Content inventory: articles, language, special constructs (XS)
    - [ ] #urls: Document old URL structure (XS)
  - [ ] #spike: Hugo spike (S) :#inventar
    - [!] #math-check: Check formula rendering (XS) :#content-inv
    - [ ] #admon-check: Try admonition rendering (XS)
  - [ ] #migration: Content migration (L) :#spike
    - [ ] #conv-script: Conversion script (XS)
    - [ ] #conv-review: Visual review per article (S) :#conv-script
  - [ ] #theme: Layout and theme (L) :#spike
  - [ ] #ci: Build and deployment with Werkator (M)
  - [ ] #cutover: Go-live (M) :#migration,#theme,#ci
    - [ ] #qa: Acceptance: old vs. new comparison, redirects (S)
    - [ ] #switch: Switch webroot (XS) :#qa

---
#math-check
  High risk, since it is unclear whether old articles contain formulas.

The notation is deliberately plain, so it stays easy to edit as plaintext and readable as a diff:

• Indentation maps the decomposition. - means a mandatory sub-package (all of them), | an alternative (one of them), + an optional extra.
• The status box says where a node stands: [?] idea, [ ] planned, [~] in progress, [/] breakthrough, [x] done, [^] in production, [-] discarded, [!] high risk.
• (S) is a T-shirt size, #math-check an ID, :#content-inv a dependency, %% a comment.
• Below the --- separator are notes per ID: findings, decisions, discards.

The editor renders a live diagram with status colors from this. For steering the work, however, the text file matters, not the image. Still, the rendered diagram is a good way to watch the AI agent’s progress.

How the Plan Steered the Work

#

The agent did not just read the Werkbaum, it maintained it continuously. The rules were simple:

1. Take the next node whose dependencies are [x]. Set it to [~].
2. Every change is a commit, with the ID at the front of the commit message. Before every commit, the Hugo build must be error-free.
3. Findings and decisions go into the node’s note, including the discarded alternatives and the reasons.
4. Decisions that are mine as product owner are presented to me as two to four options with effort, risk, impact, and reversibility. The recommendation comes first.

As a result, the Git log reads like the plan:

105a531 #inventar: Inventory completed
d852bac #conv-script: Conversion script and content import
1fd047b #conv-review: Visual review of all articles and pages
b94fb47 #theme-spike: PaperMod, Congo, and Blowfish as candidates
6a96673 #theme-base: Blowfish as default environment
5324e13 #redirect-map: Generated .htaccess with 325 redirects
0b7e95b #werkator-build: Werkator configuration, link check, deploy script
f6e9fdc #qa: Acceptance on the preview domain passed

Three points show what the plan accomplished.

Risks First, and Sometimes a Risk Dissolves Into Thin Air

#

Two nodes were [!] from the start: formula rendering and formula migration. The inventory showed: not a single article contains formulas. So both nodes could be struck through with [-].

Lean Pathfinding in Miniature

#

Structure and evaluate the features to be reached, then determine which path reaches the next milestone fastest. Once one milestone is reached, determine the next reachable milestone.

Alternatives as a Spike, Decision by the Human

#

For the theme, there was a spike instead of a discussion: PaperMod, Congo, and Blowfish with the complete content. The choice fell on Blowfish; reason and discarded candidates are in the note.

The Plan May Change, but Visibly

#

The tree at the end is not the tree from the start. The redirect map became its own work package, dark mode moved to “after cutover”. Every change is a diff to a text file and thus part of the Git history.

Why This Suits Agentic AI

#

I use Werkbaum without AI too, e.g. as a discussion basis for project planning with colleagues. But in work with an AI agent, the Werkbaum proved a very effective tool. The reasons are:

The plan is text in the repository. The agent reads and writes it with the same means as the code. It needs no API to a ticket system, no integration, no permissions. And I see every change to the plan in the same diff as the change to the code.

Decomposition, dependencies, and status are explicit. An agent need not guess what is next. It sees which nodes are free, which are blocked, which carry [!] and therefore must be clarified first. T-shirt sizes help with scoping: An XS node is a unit of work that an agent can cleanly complete in one go.

Discards stay put. That matters more for agents than for humans. An agent without memory happily proposes again what was discarded two hours ago. Everything stays in the plan with [-] and a reason.

The plan is my review surface. I did not have to read every commit. The notes with finding and decision are exactly the documentation nobody else writes.

Decision points for the human are nodes. #theme-choice, #switch: Where the agent should not decide, the plan says so. That keeps the agent’s autonomy large without anything slipping past me.

The result, read from the Git history: From the first commit with the plan to the accepted preview on the test domain took one working day. Most of my own time went into decisions and visual reviews, not implementation.

What Does Not Belong in the Plan

#

After acceptance came content corrections: Profile, homepage text, a language switcher as a click-through button instead of a dropdown, the audio players lost in the theme switch. These commits carry no Werkbaum ID. That is intentional, since the Werkbaum plans structure and key features, not every detail.

I also saw one limit: The notes grew to almost 500 lines over the course of the day. The tree itself stayed clear, but whoever looks for a decision’s history must read. The rendered diagram, however, shows each node’s explanations directly.

Status and Outlook

#

The migration is done, and once this article is online, the go-live was also completed through my approval on the test stage.

Werkbaum itself can be tried at werkbaum.javagil.de, the source code is available on GitEA under the MIT license.

An article about my general way of working in software development with agentic AI in somewhat larger projects follows shortly.

This article was translated from German with AI assistance.