AI workspace · Architecture & Training
Sections

Builder guide

Getting Started.

Join the Agency OS repository safely, understand the production boundaries, and make a first reviewable contribution.

Repository And Working Agreement

GitHub is the source of truth for code and pull requests. Asana remains the task and human-review surface. Builder work is isolated, tested, reviewed, and never promotes production automatically.

Open the Agency OS repository -> Clone the monorepo, inspect current work, and open reviewable pull requests.

Start with the rules

Read AGENTS.md before changing the platform. It owns workspace, branch, deployment, architecture-log, and secret-handling rules.

Stanley's recommended first pass is to run the repository locally, trace one existing workflow end to end, and then take a bounded documentation, test, or non-production reliability improvement through review.

First-Day Setup

1
Install the prerequisites

Use Git, GitHub CLI, Node.js 20 or later, and npm 11.14.1. Request Asana or Cloudflare access only when the assigned work requires it.

2
Clone and install

Clone https://github.com/Living-Online/agency-os.git to C:\dev\agency-os, enter the directory, and run npm ci.

3
Verify the coordinator

Run npm run agent:workspaces -- doctor and npm run agent:check. C:\dev\agency-os stays clean; the Box checkout is read-only reference material.

4
Prove the baseline

Run the focused package checks first, then npm run check and npm run build when establishing a full local baseline.

Make A Safe Change

Before implementation, fetch origin/main, inspect active worktrees, remote branches, and open pull requests, then claim only the files or system area you own.

1
Confirm the task

Write down the problem, intended outcome, acceptance criteria, risk, integrations, checks, reviewer, and any approval-gated actions.

2
Check for overlap

Run git fetch origin, git worktree list, git branch -r, gh pr list, and npm run agent:workspaces -- status. Coordinate before touching a claimed path.

3
Create a managed worktree

Run npm run agent:workspaces -- start "short-task-name" --owner "Stanley" --area "exact/path". Use one owner and one purpose per worktree.

4
Work from fresh main

The branch must start from freshly fetched origin/main. Rebase once more immediately before review and rerun the relevant checks.

5
Hand off evidence

Run npm run agent:check -- --phase handoff and provide changed files, exact checks/results, risks, exclusions, and the requested reviewer action.

Do not implement in the coordinator checkout, copy files between worktrees, or develop in C:\Users\...\Box\Living Online\agency-os.

Production-Level Workflow Checklist

  • Name the human and system sources of truth; do not create a second hidden queue, registry, or authority.
  • Make identity, environment, Business Unit, attempt, and correlation boundaries explicit and fail closed when they are ambiguous.
  • Keep state transitions deterministic, fenced, idempotent, retry-safe, and observable; concurrent progress must win over stale recovery.
  • Separate read-only evidence collection from approval-gated external writes, and preserve a clear human review point.
  • Treat provider, browser, task, and model inputs as untrusted; sanitize errors and never persist secrets or unrestricted payloads.
  • Design partial-failure behavior deliberately: useful independent evidence may continue with caveats, but missing authority or identity must block.
  • Persist durable evidence, provenance, version identity, and rollback information before claiming a capability is promoted or live.
  • Test the real boundary: schema-compatible SQL, exact request/response shapes, idempotency, retries, partial failure, authorization, and responsive/accessibility behavior where relevant.
  • Update ADRs, runbooks, release truth, the architecture change log, and this site whenever the architecture or operating contract changes.

Definition Of Done

  • The branch is rebased on current origin/main and contains only its declared scope.
  • Focused tests pass, plus typecheck, lint/format, build, release-truth, migration, or architecture checks proportional to the change.
  • The worktree handoff gate passes and the PR states the exact evidence, risks, rollback, exclusions, and reviewer decision needed.
  • A human reviews and decides the merge. Merged code is not automatically deployed, migrated, promoted, or live-verified.
  • The managed claim, worktree, and branches are cleaned after merge or explicit abandonment.

Production Boundary

Builders may prepare

  • Code, tests, migration candidates, documentation, review artifacts, preview plans, and rollback instructions.
  • Read-only diagnostics inside the assigned system boundary.

Specific approval is still required

  • Merge, production deployment, D1 apply, flag or setting changes, provider writes, Asana delivery writes, and client-visible actions.
  • Any secret creation, rotation, disclosure, or movement between systems.

An approved production Worker promotion uses the exact current origin/main commit, proves there is no interruptible live work or concurrent deploy, verifies that exact commit, deploys one Worker at a time, records the version, and then checks real live behaviour.

Where To Go Next

Platform Architecture Understand the live Cloudflare control plane and data boundaries. Platform Build Learn the task, delegation, review, and human approval loop. How To Add A Skill Follow the current skill contract and validation path. Security & Secrets Know what must stay server-side and out of artifacts. Data Sources Understand evidence roles, caveats, and source boundaries. What Is Underway Check current changes and unresolved architecture direction.

Source References