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 AP-DIGITAL-SERVICES/cfly-factory 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?

Relationship to CFactory CLI

CFactory CLI began as a fork of CFactory CLI but is now a hard fork — the codebase is maintained independently with no upstream sync. Edit any file directly as first-party code; there are no change markers or shared-file merge constraints. CFactory-specific logic that was historically isolated still lives under packages/opencode/src/cfactory/ (tests under test/cfactory/); keep related new code near those modules for consistency.

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 CFactory-only config key requires CLI Effect Schema change in AP-DIGITAL-SERVICES/cfly-factory and JSON Schema overlay change in CFactory-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/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 CFactory-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 AP-DIGITAL-SERVICES/cfly-factory.

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 CFactory-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