How we build the Harbor Business relay, and the template behind every client relay
We are building our own Buzz relay, run by one uber agent, Harbor Master. Every piece is built twice at once: once for us, and once as a generic template. A client relay is that template plus one settings file. This page explains the plan, who does what, how a change ships, and what is left to do.
1. The short version
- The goal. Stand up Harbor Master as the PRD describes. Build every piece so it serves twice: for Harbor Business, and as the template for client relays.
- The method. A template holds generic files. A values file holds one client's settings. Render the template with the values, apply it with the Buzz CLI, and you get a relay. No hand edits.
- The gate. Every change passes eight gates, Harbor Master's own work included. Jordan approves every merge. After a recorded approval, Harbor Master merges and deploys.
- The record. The
logbookrepo records every step, command, decision, and failure. If it is not in the logbook, it did not happen. The logbook becomes the SOP, Launch Kit Module 3, and the client template. - The order. Five phases, ordered by dependency. No calendar dates. Foundation, pipeline proof, team and tooling, the launch queue, then a template proof on a throwaway relay.
- Done when the relay runs, one change ships through all eight gates, the logbook captures everything, the launch list is tracked work, and a throwaway relay builds from the template with no hand edits.
2. What we are building
Four layers. Each has one owner. The logbook records all of them.
| Layer | What it holds | Owner |
|---|---|---|
| Product: Harbor | Open-source community software (AGPL): memberships, gated spaces, classroom, billing. Runs on the client's server. A plugin system is planned. | Built through the pipeline. Optional per client. |
| Relay: Buzz | Channels, agents, workflows, canvases, notes, issues. The operations layer behind every paid rung. | Harbor Master |
| Code: Gitea | Repos, pull requests, CI, deploy. The system of record for code (ADR 0003). | Harbor Master builds. Jordan approves. |
| Machine | Relay host, containers, network, backups, relay secrets, runtime config. Details stay out of the logbook. | Arsenale |
3. Who does what
One human decides. One agent runs the relay. A separate agent runs the machine. Builder, reviewer, and QA agents arrive in Phases 1 and 2.
| Decision | Who decides |
|---|---|
| Merges and deploys | Jordan approves. Harbor Master merges after a recorded approval (ADR 0009). |
| Tasks inside the approved plan | Harbor Master proceeds without asking (plan section 5.3). |
| Anything outside the plan, spending, business facts | Jordan |
| Secrets and credentials | A human enters them. Later, onecli. Agents never hold them. |
| Machine layer: host, containers, network, runtime config | Arsenale, on Jordan's request |
4. How one change ships
Every change passes the same eight gates. No exceptions for Harbor Master's own work. Phase 1 proves the whole chain with one small change.
#the-bridge, and a workflow wakes Harbor Master to merge (ADR 0010, proposed). Deploy here means re-rendering the operations dashboard (ADR 0008).Where each gate stands today
| # | Gate | Target | Today |
|---|---|---|---|
| 1 | Spec | A Buzz issue with a goal, acceptance criteria, and a template note | Tasks live in PLAN.md. They become Buzz issues when Phase 1 starts. |
| 2 | Build | A builder agent on a branch | Harbor Master builds. No builder agent yet (Phase 2). |
| 3 | CI green | Gitea CI: markdown lint and the template leak check | Not built. The runner is machine layer (Arsenale). |
| 4 | Proof | Screenshots or video in the PR | By hand. This page's PR carries screenshots. |
| 5 | PR open | Pull request on Gitea | Live. PRs #1 to #4. |
| 6 | Review | Reviewer agent on a different model | Not built (Phase 1). |
| 7 | Approve | Jordan's ✅ on the request in #the-bridge | Jordan approves in Gitea, or tells Harbor Master. #the-bridge does not exist yet. |
| 8 | Merge | Harbor Master merges through the Gitea API. Deploy follows. | Live since PR #3 (ADR 0009). Harbor Master re-renders the dashboard by hand in the same turn. |
5. Template plus values makes a client relay
This is the core of the client offer. The template is generic. The values file is one client. Two tools turn them into a running relay. The goal: same template plus same values gives the same relay, every time.
The six template rules
- Author the template and our instance together. Do not build Harbor Business first and templatize later.
- Parameterize only what a second client would change. Everything else stays literal.
- No instance values inside
template/. CI will grep for every instance value and fail on a hit. - No secrets anywhere. A template names a secret slot. A human fills it.
- Every artifact has an apply step: a Buzz CLI command, or the exact click a human makes.
- The logbook records the real build. If the template disagrees with the logbook, the logbook wins and the template gets an issue.
6. Where Harbor fits
Harbor is the product members use. Some clients will want it with their relay, some will not. So Harbor is part of the template as an option, not a requirement.
| Piece | Plan item | What it gives the template |
|---|---|---|
| Harbor plugin system | Phase 3, PRD item 2 | A standard way to add features per client. First plugins: Stripe payments, then the proof-of-work token. |
| Stripe membership wiring | Phase 3, PRD item 3 | Payments that pass in test and live mode. Live mode needs Jordan. |
| Operator quickstart | Phase 3, PRD item 4 | One runbook installs Harbor on a fresh server. It doubles as template proof. |
| Operations proof | Phase 3, PRD item 5 | Backup, restore, update, rollback, monitoring. Machine layer, with Arsenale. |
harbor block in each values file: on or off, and which plugins. And a template/harbor/ section that wraps the operator quickstart. This needs a plan PR before anyone builds it.
This page is itself a first, small plugin. It lives at template/plugins/plan-explainer/: a manifest plus a static web server with no dependencies. Its manifest is our own format until Harbor's plugin system defines one. Then it moves over.
7. Capturing what it takes to repeat this
This relay is for us. Its second job is to teach us how to build the next one, for a client, with Harbor if they need it, the same way every time. That only works if we write down every skill and every manual step as we hit it.
Where each kind of knowledge lives
| Knowledge | Captured in | Status |
|---|---|---|
| Every step, command, config, and failure | log/YYYY/MM/ daily files | Live since first boot |
| Why each choice was made, and the alternatives | decisions/ (ADRs) | 10 so far |
| The current shape of the system | maps/architecture.md | Updated in the same PR as each change |
| State passed between agent sessions | handoffs/ and the handoff-latest memory | Live |
| Generic, reusable artifacts | template/ | 3 of 11 kinds exist |
| One client's settings | instances/<slug>/values.yaml | Harbor Business only |
| Agent skills: render, apply, approval gate, dashboard deploy, handoff | Persona packs and procedures in template/agents/ | Planned, Phases 1 and 2 |
| Steps only a human can do | The apply note on each artifact (rule 5) | Partial |
| Machine-layer steps | Arsenale's own records. Machine facts stay out of the logbook. | Open: see section 9 |
Manual steps we already hit
Each one is a step a client setup must script or document. All are in the logbook for 2026-11-20.
- The runtime only listens to channels in its config. Every new channel needs a config change and a restart. Machine layer.
- The runtime answered only its owner. A second person needed an allowlist entry before their mentions reached Harbor Master.
- Channel drafts need an owner attestation. Without it,
buzz projects add-channelfailed. It is set now, but at 22:57Z the relay still rejected the drafts. Open with Arsenale. - New channels are owner-reviewed. Jordan saves each one in Buzz Desktop. One click per channel.
- The Gitea bot cannot set branch protection or webhooks. HTTP 403. A repo admin does it.
- Buzz workflows on this relay cannot run approval steps or write canvases (ADR 0010). The agent does those steps instead.
The test that we captured enough: Phase 4 builds a throwaway relay from the template and a fake client values file, with no hand edits. Phase 2 adds render-and-diff checks before that.
8. Roadmap checklist
Ordered by dependency. No dates. State as of 2026-11-20T23:04Z.
Phase 0: Foundation In progress
- 0.1 Plan and repo skeleton
- 0.2
logbookon Gitea, plan PR opened and merged - 0.3 Buzz project
harbor-business, home#harbor-master,logbookannounced in Buzz - 0.4 Draft
#the-bridgeand#shipyardThe relay rejects the drafts: "observer frame is not authorized for this agent owner" (22:57Z). Needs Arsenale. - 0.5 Topic, purpose, and canvas per channel Done for
#harbor-master. The others wait on 0.4. - 0.6 Core memory and the handoff protocol
- 0.7 Spikes, one ADR each
- 0.7a Workflow YAML (ADR 0010, proposed in PR #4)
- 0.7b Persona pack format
- 0.7c Desktop channel templates
- 0.7d Buzz and Gitea linking
- 0.8 Backfill the logbook from first boot
- 0.9 Runtime config (Arsenale)
- Owner attestation (
BUZZ_AUTH_TAG) set #harbor-masteradded to the runtime's channel list- Allowlist entry so a second person's mentions reach Harbor Master
- Add
#the-bridgeand#shipyardonce they exist
- Owner attestation (
Phase 1: Pipeline proof Next
- CI on Gitea: markdown lint and the template leak check The runner is machine layer (Arsenale).
- Reviewer agent as a template persona pack, on a different model than the builder
- 1.1 Approval request posted in
#the-bridgeNeeds 0.4. - 1.2 Approval record: Jordan's ✅ reaction, and a workflow that wakes Harbor Master
- 1.3 Merge through the Gitea API Done by hand under ADR 0009 since PR #3. Automatic after 1.2.
- 1.4 Hand-merge signal: Gitea webhook to a Buzz workflow Lower priority.
- 1.5 Re-render the dashboard after each merge By hand today, in the same turn as the merge.
- 1.6 Branch protection on
mainJordan, as repo admin. - Exit: one change passes all eight gates and is logged end to end
Phase 2: Team and template tooling
- Builder (Wright pattern) and QA agents as persona packs. A strong model plans, cheap models build and check.
tools/render: template plus values produces concrete artifactstools/apply: idempotent apply through the Buzz CLI- Daily digest workflow to
#the-bridge: decisions needed, done, blocked - Exit: the Harbor Business relay layer rebuilds from template plus values
Phase 3: Launch queue
- Wave 1
- 1. Vet onecli against free open-source alternatives Unblocks every secret.
- 9. Inference billing: how the client pays for inference
- 7. Runtime call-to-action tone: helpful, not cheap
- 10. Skool migration status A fact only Jordan has.
- Wave 2
- 8. Gitea member access. Fix notification noise first. Jordan and Arsenale.
- 2. Harbor plugin system: Stripe first, proof-of-work token second Needs onecli.
- Wave 3
- 3. Stripe membership wiring, test and live Live mode needs Jordan.
- 4. Operator quickstart for a fresh server
- 5. Operations proof: backup, restore, update, rollback, monitoring Machine layer, with Arsenale.
- 6. Landing page Needs confirmed pricing.
- Wave 4
- 11. Module 3 depth, sourced from the logbook of Phases 0 to 3
- Exit: every item tracked, each with a visible PR
Phase 4: Template proof
- Stand up a throwaway relay from the template and a fake client values file
- Split
template/into its own repo if the ADR 0002 trigger fires - Exit: criterion 5 passes
Done criteria
- 1. The relay runs. Harbor Master answers on
#harbor-master. The runtime subscribed to#harbor-masterat 22:08:37Z. An answer there is not yet tested. - 2. One change completes the full pipeline, spec to auto-deploy, with the human gate on
#the-bridge. - 3. The
logbookcaptures every action from first boot. Holds today. It must keep holding. - 4. The launch to-do list shows as tracked work with visible PRs.
- 5. A throwaway relay is configured from
template/plus a values file, with no hand edits.
9. Open decisions and blockers
Decisions
| Question | Who |
|---|---|
| Approve plan revision 4 and ADR 0010 (PR #4). | Jordan |
| Core-team access: who besides Jordan may direct Harbor Master, and for what kinds of work. | Jordan |
| Public access to this page. Anyone with the URL can read the internal plan. Prices are already left out. | Jordan |
When to add Harbor to the template: the proposed harbor values block and template/harbor/. | Jordan |
| Where machine-layer steps get recorded, so client relays can be built end to end. | Jordan and Arsenale |
| Inference billing mechanism. The client pays. How exactly is open. | Research in Phase 3, then Jordan |
| Managed Harbor scope and price. Deferred until real costs are known. | Jordan |
| Premium DWY delivery hours. The hour cap is not set. | Jordan |
Blockers
| Blocker | Blocks | Who unblocks |
|---|---|---|
| The relay rejects channel drafts: "observer frame is not authorized for this agent owner". | 0.4, then 1.1, 1.2, the digest | Arsenale |
| No CI runner for Gitea. | Gate 3 | Arsenale |
Branch protection on main. | 1.6 | Jordan |
| A public URL for this page. | Viewing without Tailscale | Arsenale |
10. Appendix
A. Buzz commands the template uses
| Buzz primitive | Command | Template artifact |
|---|---|---|
| Projects | buzz projects create | template/project.yaml |
| Channels | buzz projects add-channel, channels topic, channels purpose | template/channels/*.yaml |
| Canvas | buzz canvas set | template/canvases/*.md |
| Agents | buzz agents draft-create, buzz pack validate | template/agents/<role>/ |
| Workflows | buzz workflows create, trigger | template/workflows/*.yaml |
| Issues | buzz issues create, assign, status | template/issues/*.md |
| Repos | buzz repos create --clone <gitea-url> | template/repos.yaml |
| Notes | buzz notes set | template/notes/*.md |
| Memory | buzz mem set | template/memory/core.md |
| Reactions, emoji | buzz reactions add, buzz emoji import | template/emoji.json |
| Media, status, search | buzz upload file, users set-status, messages search | none |
B. Repository layout
logbook/
PLAN.md the plan. Changes go through a PR.
AGENTS.md rules for any agent working here
sources/ PRD and brief index. Operator-only facts redacted.
log/YYYY/MM/YYYY-MM-DD.md timestamped entries
decisions/NNNN-*.md decision records
maps/architecture.md system map, updated with each change
handoffs/ one file per finished task
template/ generic, parameterized artifacts
plugins/plan-explainer/ this page's web server
instances/harbor-business/ our values file, and this page
tools/ render and apply (Phase 2)
C. Decisions so far
| ADR | Decision |
|---|---|
| 0001 | Every artifact is a generic template plus instance values. |
| 0002 | One repo now. Split the template out later, on a trigger. |
| 0003 | Gitea for code, PRs, CI, and deploy. Buzz for conversation, the queue, and approvals. |
| 0004 | Every task ends with a handoff. Each task starts from a fresh session. |
| 0005 | The plan itself went through the gate. |
| 0006 | Harbor Master is the Claude Code runtime. One agent, not an agent plus a tool. |
| 0007 | Source briefs stay local, outside git. |
| 0008 | Deploy means publishing the operations dashboard. |
| 0009 | Harbor Master merges after Jordan's recorded approval. |
| 0010 | Proposed: approval is Jordan's ✅ reaction. Workflows only wake Harbor Master. |
D. Terms
| Harbor | The product members use. Open-source community software that runs on the client's server. |
|---|---|
| Buzz | The operations layer. Agents and humans work in its channels. Never the member-facing UI. |
| Relay | One Buzz server. Ours is Harbor Business. Each client gets one. |
| Uber agent | The one agent a relay's owner talks to. Here, Harbor Master. |
| Beacon | The proprietary harness that installs Buzz, the agent runtimes, and the integration for a client. |
| Template, values file | Generic artifacts, and one client's settings that fill them. |
| Persona pack | The unit we send to a relay: one or more agent definitions. |
| Wright, GridWalker | The builder and reviewer patterns already running for Harbor. |
| onecli | The planned secrets service. Vetted against open-source alternatives first. |
| Canvas | A channel's pinned document. The admin canvas is our operations dashboard. |