Development Patterns

This page turns architecture boundaries into contributor decisions. Read Architecture Overview and relevant subsystem page first, then use this guide before editing architecture-facing code in stemcat/biggi or its cross-repository contracts.

How to use this page

1. Identify owning subsystem in architecture docs.
2. Choose narrowest source boundary that can hold change.
3. Update generated or cross-repository contracts when public surface changes.
4. Run smallest relevant checks plus affected repository guards.

Where should change live?

BIGGI-owned boundaries

BIGGI's embedded runtime forks upstream OpenCode. Prefer BIGGI-owned directories and packages for additive behavior:

Shared OpenCode files

Use biggi_change markers when BIGGI-specific code must modify shared upstream files.

Marker exemptions apply to paths already owned by BIGGI, including paths whose names contain biggicode and BIGGI packages such as packages/biggi-vscode/ or packages/biggi-ui/. Do not add markers there.

Embedded runtime API

The embedded runtime server uses Effect HttpApi and publishes OpenAPI-compatible HTTP + SSE surfaces consumed by the JavaScript SDK and active clients.

SDK generation

Embedded Runtime SDK contract owns generation pipeline detail. Contributor rules are short:

Runtime config schema

Runtime config loading and editor validation are separate paths. A new BIGGI-only config key requires an embedded runtime Effect Schema change in stemcat/biggi and a JSON Schema overlay change in BIGGI-Org/cloud. Follow Runtime Config Schema for the exact workflow.

Module export pattern

For new public APIs, prefer flat ESM exports inside module, then namespace re-exports from index files when grouped access helps callers.

// packages/opencode/src/session/session.ts
export const create = fn(CreateSchema, async (input) => {
  // ...
})

export const list = fn(ListSchema, async (input) => {
  // ...
})

// packages/opencode/src/session/index.ts
export * as Session from "./session"

Import specific export when practical. Use namespace shape (Session.create) when preserving existing API or grouped module access improves clarity. Existing BIGGI-owned namespaces remain valid; do not refactor them solely for style.

Tool implementation

Tools use Tool.define("id", Effect.gen(...)) with Effect Schema validation and typed execution.

export const ExampleTool = Tool.define(
  "example",
  Effect.gen(function* () {
    return {
      description: "Example tool",
      parameters: Schema.Struct({
        value: Schema.String,
      }),
      execute(args) {
        return Effect.succeed({
          title: args.value,
          metadata: {},
          output: args.value,
        })
      },
    }
  }),
)

Reuse tool helpers, permission gates, and telemetry conventions before adding abstractions. Tests should exercise implementation behavior rather than duplicating logic in mocks.

Build system

Documentation changes

When adding or moving docs pages:

• Create page under pages/.
• Update matching navigation file in lib/nav/.
• Add redirects when removing or moving routes.
• Use compact markdown tables with unpadded cells.
• Use /docs prefix for docs image paths.

Source map

Paths below are relative to stemcat/biggi.

Upstream merge workflow

bun install runs script/setup-git.ts, which sets repo-local merge conflict style to zdiff3. Base-aware markers make manual resolution and syntax-aware tooling more useful. Upstream automation under script/upstream/ applies transforms before merge, forces zdiff3 for merge operation, and runs mergiraf against remaining textual conflicts. mergiraf is required by merge script.

From script/upstream/, use:

bun run analyze.ts --version <tag>
bun run merge.ts --version <tag> --dry-run
bun run merge.ts --version <tag>

Keep BIGGI-specific logic extracted, shared seams narrow, markers accurate, and CI guards green before upstream merge work lands.

Related pages

• Architecture Overview - system layers and reading paths
• Embedded Runtime - local runtime ownership and SDK contract
• Runtime Config Schema - cross-repository config-key workflow