Agentic design
Agentic design.
Shipright is a small agent system built in public. Two AI agents do the judgement work. Plain code does everything that must never go wrong. One written charter says which is which.
The solution
Shipright watches GitHub for work that has actually shipped (releases and merged pull requests) and turns the worthwhile pieces into short, reviewed posts on Bluesky. The News loop selects uplifting stories; Football follows FC Utrecht fixtures and results. Everything it publishes is listed on the home page. The diagram below shows the original GitHub loop; News and Football share its review, queue and publication structure.
- GitHub. Releases and merged pull requests supply the GitHub loop. News and Football have separate source tools. Nothing is written from guesswork.
- Collector. Plain Python, not an agent. It fetches new items and stores each one as a pending source.
- Sources. One private SQLite database holds repositories, sources, posts and AI usage receipts. The website receives public exports, not database access.
- Content scout. An agent reads each source with the product context and the post templates. It either rejects it with a reason or approves it and writes the draft.
- Ready posts. Approved drafts wait here, unchanged.
- Publication gate. Code, not the model, checks that the configured interval since the last send has elapsed. If it has not, the post stays ready until the next allowed time.
- Publisher. An agent plans its work, selects a ready post, records why it chose it and sends the reviewed text to Bluesky once. It then sets its next wake time. The receipt is saved, and only published posts are exported to
published-posts.json, which this website reads.
Two agents, one queue
Shipright has exactly two application agents, the content scout and the publisher. They never call each other. They share work only through the database: the scout leaves approved posts in it, and the publisher picks them up.
The scout works in independent cycles, covering GitHub, News, Football, Comments, operator briefs and the blog. Each has its own schedule or database wake request, so a problem in one blocks only that cycle, though a shared failure or the daily AI limit can still stop or delay any of them. Blog drafting is in testing; the first public article has not yet been proven. A Football fixture announcement was published on 5 Nov 2026.
Each agent gets a short list of narrow tools and nothing else. It has no shell or broad file access. Configured research tools can search the web within their limits. Credentials stay outside the model. Tools validate their inputs and call the configured providers; the model does not receive credentials or control the website uploader.
Small components with separate jobs
- Source modules: GitHub, News and Football provide their own collection, evidence and editorial tools.
- Tool library: declares which tools each agent can use. The model chooses among those available tools.
- Prompt catalogue: assembles the agent instructions, Klaus guidance and cycle context. Templates guide writing; they do not choose the work.
- Communications adapters: translate channel operations. Bluesky is the live social destination; an adapter boundary does not mean other networks are enabled.
- Runtime: starts due work, enforces budgets and controls, and records outcomes in SQLite. It does not make editorial decisions.
- Website exporter: produces the public feed and admin snapshot. It runs as ordinary code, outside the model's decisions.
From comment to reply
A separate listener checks Bluesky every three minutes without an AI call. It stores new comments in SQLite. Database wake requests make eligible work available to the publisher and Comments scout cycle:
- The publisher hands the stored comment to Klaus for a response.
- The scout reads the original post and conversation, makes a plan and saves a reviewed reply.
- The ready reply requests publisher work. The publisher checks the limits, sends through the Bluesky adapter and records the receipt.
A wake request does not bypass a stopped robot, exhausted budget, reply limit or uncertain earlier send. Eight successful replies were recorded by 8 Nov. That is delivery evidence, not a promise of instant responses or continuous health.
The tool lists below illustrate GitHub drafting and publishing; other cycles use their own tool sets.
Inside a content scout run
- Decides Make a work plan.
inspect_run · save_work_plan - Decides Pick a repository; collect if stale.
list_repositories · collect_updates - Decides Pick the next pending update.
list_work · select_work - Tool Read the update, product and templates.
read_source · read_product · list_templates - Decides Approve or reject, always with a reason.
save_review - Decides If approved: template, wording, draft.
save_review · code checks the draft - Decides Next item, or finish the run.
list_work · finish_run
Inside a publisher run
- Decides Make a work plan.
inspect_run · save_work_plan - Decides Pick the next ready post.
list_work · select_work - Tool Read it: text and image stay as approved.
read_post - Tool Check the publishing window.
check_publish_window - Decides Record why this post was chosen.
save_selection_reason - Tool Publish once; code rechecks eligibility.
publish_once - Decides Set next wake, then finish the run.
set_next_wake · finish_run
These are tool capabilities, not a fixed script. Each agent makes and revises its plan. The system saves public copies of its state after changes; exporting is not something an agent can do. A database records each run's outcome, tool results and reminders. The public admin page shows an exported snapshot that refreshes within seconds and says so when updates stop. It is not a connection to the database.
The charter
Shipright's agent architecture charter was agreed with Chris on 31 October 2026. Every builder reads it before changing an agent's tools, prompts or lifecycle, and every review checks the work against it. Its core idea fits in one line: the agent decides; code enforces.
The agent decides
What work to look at, what to do next, whether a change is worth a post, which template fits, and when to check again.
Code enforces
Valid inputs, allowed state changes, the SQL-configured posting interval (checked again at send time) and real receipts. Choosing its own actions never lets an agent bypass a rule.
Tools stay narrow
Fetching from GitHub, sending a post and exporting the feed are small, predictable functions, never open-ended abilities.
Evidence before claims
Nothing is called live until a recorded live run shows the model choosing its tools and the resulting changes. A saved plan or an imported code library is not proof.
Guardrails in code
These rules are enforced by code, whatever the AI decides.
- SQL-configured publication spacing, checked before publishing starts and again at the moment of sending.
- The publisher sends the reviewed text unchanged. It cannot rewrite what the scout approved.
- Every rejection and approval carries a reason, so each decision can be audited.
- Token use is recorded for every completed AI response.
- The agents share a daily AI spending limit: US$20 in the Development setting or US$1 in the Production setting, reset each day and checked before every AI call. Shipright is currently in Development. Spending is recorded by setting and day.
- Settings verified on 8 Nov: 30 GitHub posts per UTC day across all repositories; 10 News posts per Auckland day; a shared five-minute minimum between sends, including replies. These SQL values are ceilings, not targets.
- An unpublished GitHub source, and any ready draft made from it, becomes ineligible 48 hours after the source's own timestamp. This rule covers GitHub work only, not News articles.
- An invalid Football draft gets feedback for one rewrite. If it remains invalid, it is not queued; the scout can move on or finish its run.
- A failed publication stops. There is no blind automatic retry.
- The public website reads only the exported feed of published posts. It never touches the database or credentials.
Personality and voice
Shipright's posts are written by Klaus, a fictional AI editorial persona: a Dutchman in San Francisco who misses proper Gouda. He is married to Aroha, a New Zealander, and he is an avid FC Utrecht supporter. None of that is real. Klaus is a writing device, never a Shipright employee, a customer, a source or someone who attended a match.
Plain and specific
Practitioner tone, in NZ English. Each post leads with one concrete fact: a number, an order of steps or a named check, explained so a non-developer can follow.
Dry, and aimed inwards
European understatement with American enthusiasm. The teasing is aimed at Chris, the developer, and at Shipright's own engineering. Never at customers, contributors or anyone outside the work.
Limits on the humour
No jokes about children, disabilities, gender or illegal activity. Emoji are rare, at most one hashtag, and no hype words such as game-changing, seamless or unlock.
Facts come first
The fact and its source come before any joke. Klaus never invents an experience, a result or a quote to make a line work.
An approved example, written about a real change: "Shipright now saves the review and the ready post in one transaction. Chris briefly considered making the AI tick two boxes. The database declined the paperwork. One saved decision, one ready post, and the publisher can get on with it. — Klaus (AI)"
The charter's split applies to personality too. The agent decides the wording, the angle and whether a joke fits, guided by templates and the voice rules. It is also the scout's job to keep each claim faithful to the saved source, and it approves or rejects every draft with a reason. Code enforces what code can check: the inputs and allowed state changes, the posting limits, and that the publisher sends the approved text unchanged. Code cannot judge whether a claim is true, so source fidelity rests on the scout's review and on the recorded reasons that make it auditable.
Klaus's shared voice guidance applies to GitHub, News, Football and replies. His operator-controlled humour setting is 5 out of 10: roughly half of suitable messages, not a compulsory joke. Football fixtures and results have been published, and successful comment replies are recorded in the database. Posts should offer useful facts and character, without internal release-note caveats. The Delivery page distinguishes delivered behaviour from work still being proven.
The lesson
Write down who decides. Version 1 ran as fixed steps that an operator started by hand. That was honest for a first proof, but it was a pipeline with AI inside, not an agent choosing its work.
Writing the charter split every responsibility in two: judgement for the model, rules for the code. That made the guardrails testable and gave reviewers a clear test to apply to each change. Changes are built and independently reviewed against the same charter. The review checks tests, contracts and delivery claims.
Progress against all of this is tracked on the Delivery page.