Contributing

How the repo is organized and the conventions to follow when contributing.

Cyborg7 is a fork of Paseo. Most packages are upstream Paseo code and stay as close to upstream as possible; our additions live in clearly-owned places.

Repo layout

packages/
  server/
    src/server/
      agent/    # Paseo (upstream) — agent lifecycle, providers. Don't modify.
      cyborg/   # Cyborg7 — workspaces, channels, tasks, auth, storage, relay-standalone
        db/     # Drizzle schema + PostgreSQL
  ui/           # Svelte 5 UI ("blank Slack" collaboration shell)
  relay/        # workspace-aware relay broker
  cli/          # terminal CLI (cyborg subcommands)
  cybo-runner/  # standalone Cybo CLI
  desktop-cyborg/  # Electron shell (cloud-only)
  docs/         # these docs (Astro Starlight) — built separately
knowledge/      # architecture docs and design decisions

Ownership rules

• Never modify Paseo's agent code (packages/server/src/server/agent/) directly — extend or hook from cyborg/ instead, to minimize upstream merge conflicts.
• Cyborg7 logic belongs in packages/server/src/server/cyborg/ and packages/ui/.
• When a task is scoped to one package, don't touch files outside it unless the task explicitly requires it.

Conventions

• Commits: Conventional Commits (feat:, fix:, chore:, refactor:).
• TypeScript: strict mode; named exports; PascalCase component files.
• Lint/format: oxlint + oxfmt (pre-commit hooks via lefthook).
• Package manager: pnpm only.
• No Spanish in code (variable names, comments). UI strings may be English or Spanish.

Build & test

pnpm install
pnpm dev          # daemon + UI dev servers
pnpm build        # production build
pnpm typecheck    # typecheck all packages
pnpm test         # vitest

Editing these docs

The docs site is packages/docs (Astro Starlight). It is excluded from the monorepo workspace and builds independently, so doc changes never affect product releases:

cd packages/docs
pnpm install
pnpm dev          # http://localhost:4321