Internal · Harbor Business · Build plan explainer

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.

Source: the logbook repo, PLAN.md revision 4 (Gitea PR #4, waiting for Jordan's approval), the PRD, and decision records 0001 to 0010. Written by Harbor Master, 2026-11-20T23:04Z. Prices are left out on purpose.

1. The short version

2. What we are building

Four layers. Each has one owner. The logbook records all of them.

System layers Four stacked layers: Product (Harbor), Relay (Buzz), Code (Gitea), and Machine. Members use only Harbor. The logbook spans every layer. Buzz is never the member-facing UI. Members Product: Harbor Members use this. Optional per client. Memberships Gated spaces Classroom Billing Plugins Relay: Buzz Owner: Harbor Master Channels Agents Workflows Dashboard Issue queue Code: Gitea Builds: Harbor Master Approves: Jordan logbook repo Pull requests Merge API CI checks Branch rules Machine Owner: Arsenale Relay host Containers Network Runtime config Relay secrets logbook records every step in every layer exists not built yet
Diagram 1. The four layers. Members only ever touch Harbor. Beacon, the harness that installs this stack for a client, is built from the same template.
LayerWhat it holdsOwner
Product: HarborOpen-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: BuzzChannels, agents, workflows, canvases, notes, issues. The operations layer behind every paid rung.Harbor Master
Code: GiteaRepos, pull requests, CI, deploy. The system of record for code (ADR 0003).Harbor Master builds. Jordan approves.
MachineRelay 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.

Who does what Jordan directs Harbor Master and approves merges. Harbor Master sends machine needs to Arsenale through Jordan. Harbor Master sends specs to the planned builder, reviewer, and QA agents in #shipyard and gets pull requests back. Jordan Owner Sets direction and scope. Supplies business facts. Approves every merge. Saves drafts in Desktop. Gitea admin: branch rules and webhooks. Harbor Master Uber agent · Claude Code Plans, specs, and builds. Runs the eight gates. Merges after approval. Deploys the dashboard. Logs every step. Never holds credentials. Arsenale Machine layer Relay host, containers, network, relay secrets. Runtime config, restarts. CI runner (Phase 1). Public URLs. Escalation target only. directs approval requests machine needs via Jordan specs, issues PRs, results #shipyard · planned for Phases 1 and 2 Builder Wright pattern Builds on a branch Opens the PR Reviewer GridWalker pattern Different model Approves or loops back QA Cheap model Checks the work before review Clients see one uber agent. Build chatter stays in #shipyard. Default per project: builder and reviewer, both visible, on different models.
Diagram 2. Roles. Dashed boxes are planned. Harbor Master does not talk to Arsenale directly today. It tells Jordan what the machine layer needs.
DecisionWho decides
Merges and deploysJordan approves. Harbor Master merges after a recorded approval (ADR 0009).
Tasks inside the approved planHarbor Master proceeds without asking (plan section 5.3).
Anything outside the plan, spending, business factsJordan
Secrets and credentialsA human enters them. Later, onecli. Agents never hold them.
Machine layer: host, containers, network, runtime configArsenale, 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 eight-gate change pipeline Spec, Build, CI green, Proof, PR open, Review, Approve, Merge. Review can send work back to Build. Approve is the human gate. After the merge: re-render the dashboard, log, write the handoff, and start the next task fresh. Human gate 1 Spec Harbor Master Buzz issue 2 Build Builder on a branch 3 CI green Gitea CI lint, leak check 4 Proof Builder screenshots 5 PR open Builder on Gitea 6 Review Reviewer other model 7 Approve Jordan #the-bridge 8 Merge Harbor Master auto-deploys changes requested: back to Build After every merge, in the same turn Re-render dashboard Log with event ids Write handoff Next task starts fresh
Diagram 3. The change pipeline. Gate 7 is the human gate: Jordan reacts ✅ on Harbor Master's approval request in #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

#GateTargetToday
1SpecA Buzz issue with a goal, acceptance criteria, and a template noteTasks live in PLAN.md. They become Buzz issues when Phase 1 starts.
2BuildA builder agent on a branchHarbor Master builds. No builder agent yet (Phase 2).
3CI greenGitea CI: markdown lint and the template leak checkNot built. The runner is machine layer (Arsenale).
4ProofScreenshots or video in the PRBy hand. This page's PR carries screenshots.
5PR openPull request on GiteaLive. PRs #1 to #4.
6ReviewReviewer agent on a different modelNot built (Phase 1).
7ApproveJordan's ✅ on the request in #the-bridgeJordan approves in Gitea, or tells Harbor Master. #the-bridge does not exist yet.
8MergeHarbor 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.

How one template and one values file become a client relay The template folder and a client's values file feed tools/render. Render produces concrete artifacts. tools/apply pushes them through the Buzz CLI to the client relay. Humans add secrets and approve drafts. Arsenale provides the host, runtime, and public URLs. template/ Generic. No client values. logbook/entry formats canvases/dashboard plugins/this explainer channels/planned agents/planned workflows/planned issues/planned notes/ memory/planned project.yamlplanned repos.yamlplanned CI leak check: no client values in template/ instances/<client>/values.yaml Names: org, owner, agents Channels, git org, repos Harbor: on or off (proposed) Secret slots: names only tools/render Phase 2 fills {{ keys }} artifacts tools/apply Buzz CLI idempotent Client relay #admin #gate #build Dashboard Agents Workflows Issue queue Harbor, if wanted Arsenale host, runtime, URLs Secrets human, later onecli Owner clicks approve drafts in Desktop
Diagram 4. Template plus values. Dashed boxes are Phase 2 tools. Until they exist, Harbor Master renders by hand and logs each step. Phase 4 proves it on a throwaway relay with a fake client values file.

The six template rules

  1. Author the template and our instance together. Do not build Harbor Business first and templatize later.
  2. Parameterize only what a second client would change. Everything else stays literal.
  3. No instance values inside template/. CI will grep for every instance value and fail on a hit.
  4. No secrets anywhere. A template names a secret slot. A human fills it.
  5. Every artifact has an apply step: a Buzz CLI command, or the exact click a human makes.
  6. 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.

PiecePlan itemWhat it gives the template
Harbor plugin systemPhase 3, PRD item 2A standard way to add features per client. First plugins: Stripe payments, then the proof-of-work token.
Stripe membership wiringPhase 3, PRD item 3Payments that pass in test and live mode. Live mode needs Jordan.
Operator quickstartPhase 3, PRD item 4One runbook installs Harbor on a fresh server. It doubles as template proof.
Operations proofPhase 3, PRD item 5Backup, restore, update, rollback, monitoring. Machine layer, with Arsenale.
Proposed, not yet in the plan. A 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

KnowledgeCaptured inStatus
Every step, command, config, and failurelog/YYYY/MM/ daily filesLive since first boot
Why each choice was made, and the alternativesdecisions/ (ADRs)10 so far
The current shape of the systemmaps/architecture.mdUpdated in the same PR as each change
State passed between agent sessionshandoffs/ and the handoff-latest memoryLive
Generic, reusable artifactstemplate/3 of 11 kinds exist
One client's settingsinstances/<slug>/values.yamlHarbor Business only
Agent skills: render, apply, approval gate, dashboard deploy, handoffPersona packs and procedures in template/agents/Planned, Phases 1 and 2
Steps only a human can doThe apply note on each artifact (rule 5)Partial
Machine-layer stepsArsenale'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.

  1. The runtime only listens to channels in its config. Every new channel needs a config change and a restart. Machine layer.
  2. The runtime answered only its owner. A second person needed an allowlist entry before their mentions reached Harbor Master.
  3. Channel drafts need an owner attestation. Without it, buzz projects add-channel failed. It is set now, but at 22:57Z the relay still rejected the drafts. Open with Arsenale.
  4. New channels are owner-reviewed. Jordan saves each one in Buzz Desktop. One click per channel.
  5. The Gitea bot cannot set branch protection or webhooks. HTTP 403. A repo admin does it.
  6. 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 roadmap Phase 0 Foundation (in progress), Phase 1 Pipeline proof (next), Phase 2 Team and tooling, Phase 3 Launch queue, Phase 4 Template proof. Each phase delivers one or more done criteria. PHASE 0 Foundation In progress GOAL Repo, rules, home channel, spikes. EXIT Plan merged. Channels live. PHASE 1 Pipeline proof Next GOAL One change through all eight gates. EXIT Logged end to end. Module 3, lesson 1. PHASE 2 Team, tooling Later GOAL Builder, QA agents. Render and apply. EXIT Our relay rebuilds from template. PHASE 3 Launch queue Later GOAL 11 PRD items as tracked issues. EXIT Every item has a visible PR. PHASE 4 Template proof Later GOAL Throwaway relay, fake client values. EXIT No hand edits. Template may split. Done 1 and 3 Done 2 Sets up Done 5 Done 4 Done 5
Diagram 5. The phases, in dependency order. The done criteria are listed at the end of this section.
DonePartly doneBlockedNot started

Phase 0: Foundation In progress

Phase 1: Pipeline proof Next

Phase 2: Team and template tooling

Phase 3: Launch queue

Each item becomes a Buzz issue with a template note. Waves follow dependencies. Numbers are PRD item numbers.

Phase 4: Template proof

Done criteria

9. Open decisions and blockers

Decisions

QuestionWho
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

BlockerBlocksWho unblocks
The relay rejects channel drafts: "observer frame is not authorized for this agent owner".0.4, then 1.1, 1.2, the digestArsenale
No CI runner for Gitea.Gate 3Arsenale
Branch protection on main.1.6Jordan
A public URL for this page.Viewing without TailscaleArsenale

10. Appendix

A. Buzz commands the template uses

Buzz primitiveCommandTemplate artifact
Projectsbuzz projects createtemplate/project.yaml
Channelsbuzz projects add-channel, channels topic, channels purposetemplate/channels/*.yaml
Canvasbuzz canvas settemplate/canvases/*.md
Agentsbuzz agents draft-create, buzz pack validatetemplate/agents/<role>/
Workflowsbuzz workflows create, triggertemplate/workflows/*.yaml
Issuesbuzz issues create, assign, statustemplate/issues/*.md
Reposbuzz repos create --clone <gitea-url>template/repos.yaml
Notesbuzz notes settemplate/notes/*.md
Memorybuzz mem settemplate/memory/core.md
Reactions, emojibuzz reactions add, buzz emoji importtemplate/emoji.json
Media, status, searchbuzz upload file, users set-status, messages searchnone

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

ADRDecision
0001Every artifact is a generic template plus instance values.
0002One repo now. Split the template out later, on a trigger.
0003Gitea for code, PRs, CI, and deploy. Buzz for conversation, the queue, and approvals.
0004Every task ends with a handoff. Each task starts from a fresh session.
0005The plan itself went through the gate.
0006Harbor Master is the Claude Code runtime. One agent, not an agent plus a tool.
0007Source briefs stay local, outside git.
0008Deploy means publishing the operations dashboard.
0009Harbor Master merges after Jordan's recorded approval.
0010Proposed: approval is Jordan's ✅ reaction. Workflows only wake Harbor Master.

D. Terms

HarborThe product members use. Open-source community software that runs on the client's server.
BuzzThe operations layer. Agents and humans work in its channels. Never the member-facing UI.
RelayOne Buzz server. Ours is Harbor Business. Each client gets one.
Uber agentThe one agent a relay's owner talks to. Here, Harbor Master.
BeaconThe proprietary harness that installs Buzz, the agent runtimes, and the integration for a client.
Template, values fileGeneric artifacts, and one client's settings that fill them.
Persona packThe unit we send to a relay: one or more agent definitions.
Wright, GridWalkerThe builder and reviewer patterns already running for Harbor.
onecliThe planned secrets service. Vetted against open-source alternatives first.
CanvasA channel's pinned document. The admin canvas is our operations dashboard.