@chernabog/sdk

The blocks Chernabog flows and steps are written from (Implement, Review, Plan, Hybrid, Stack, PullRequest, prompts), over @chernabog/core, which it re-exports, so a flow imports everything from this one package.

A repo lists it in .chernabog/package.json's dependencies, at the version it chooses, and each snapshot of the repo's base branch installs it: two repos on different versions run side by side in one daemon. The chernabog binary supplies its own copies of @chernabog/core and effect at runtime, and runs this package when its peer range on @chernabog/core includes a core the binary provides. chernabog recipes upgrade moves a repo to the version released with its binary.

Flows

import { Claims, defineFlow, Implement, step } from "@chernabog/sdk";
import { Effect, Schema } from "effect";

export default defineFlow({
  trigger: Implement.triggerFor("auto:eligible"), // the work items to act on
  gate: Implement.gate, // checked before each run starts; fail with Skip to hold it back
  concurrency: 1,
  workflow: (item) =>
    Effect.gen(function* () {
      const issue = yield* Implement.issueOf(item);

      // However the run ends, its claim on the issue goes.
      return yield* Effect.gen(function* () {
        const { branch } = yield* Implement.claim(issue);
        const checked = yield* step(
          "check-scope",
          { issue },
          { output: Schema.Struct({ ok: Schema.Boolean }) },
        );
        // ...
      }).pipe(Claims.releasing(Claims.issue(issue)));
    }),
});

Implement, Review and PullRequest hold the building blocks of the review loop, each an activity a flow can reorder, leave out or wrap. Hybrid holds the blocks of the hybrid path, where a person works on an issue with the agent in an interactive session. Plan holds the blocks of the plan recipe, which turns a spec issue into an epic of sub-issues once a person approves the agent's plan. Stack brings a layer of a stack of pull requests up to date with its base by merging, including once the layer below was squash-merged, and adjusts the layer to what moved in the session that wrote it. Chernabog's recipes are complete flows written out from these blocks, which a repo bakes into its own .chernabog/flows/; they are published as @chernabog/recipes, whose source is packages/recipes/.

A flow can also give item: (key) => Effect<Option<WorkItem>>, the work item for a key a person names that the trigger doesn't report, as Hybrid.itemFor finds the issue chernabog start names.

Side effects belong inside activities or steps, never in the workflow body, which runs again on every replay.

Steps

// .chernabog/stages/find-work.ts
import { defineStage, GitHub, Skip } from "@chernabog/sdk";
import { Effect, Schema } from "effect";

export default defineStage({
  name: "find-work",
  input: Schema.Struct({}),
  output: Schema.Struct({ issue: Schema.Number }),
  run: () =>
    Effect.gen(function* () {
      const [issue] = yield* (yield* GitHub).queuedIssuesLabelled("auto:eligible");
      if (issue === undefined) return yield* new Skip({ reason: "nothing queued" });
      return { issue: issue.number };
    }),
});

Services

The services are core's: each is a port the binary provides.

Each service is a layer, so a team can replace one with its own implementation, and tests can use fakes.