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 Voyager-Org/voyager 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?

Voyager-owned boundaries

Voyager CLI forks upstream VoyagerCode. Prefer Voyager-owned directories and packages for additive behavior:

Shared VoyagerCode files

Use voyager_change markers when Voyager-specific code must modify shared upstream files.

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

CLI server API

CLI server uses Effect HttpApi and publishes OpenAPI-compatible HTTP + SSE surfaces consumed by JavaScript SDK and JetBrains build-local Kotlin client.

SDK generation

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

CLI config schema

Runtime config loading and editor validation are separate paths. New Voyager-only config key requires CLI Effect Schema change in Voyager-Org/voyager and JSON Schema overlay change in Voyager-Org/cloud. Follow CLI Config Schema for 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/voyagercode/src/session/session.ts
export const create = fn(CreateSchema, async (input) => {
  // ...
})

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

// packages/voyagercode/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 Voyager-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 Voyager-Org/voyager.

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 Voyager-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
• CLI Runtime - local runtime ownership and SDK contract
• CLI Config Schema - cross-repository config-key workflow